it being a myth is massively at odds with my experience. i'm also sure that i have data and experience... also that i can quantify why it is easy to read to some degree with logic (but measurement is king).

i know i'm fortunate to be very good at reading other people's code so my view is probably biased - its feedback i constantly get - i've never worked on a codebase where i can't contribute meaningfully on day one even when its of quite a poor quality. i've found myself explaining people's own code to themselves more than once too...

i've worked with lots of programmers and trawled through many code bases old and new... by far the easiest code for me to read is fairly devoid of comments with sensible variable names, lots of whitespace and descriptive function names and using procedural logic or sensible (not excessive) amounts of OO. hungarian notation i can take or leave...

comments don't hurt... documentation doesn't hurt, but more than once i've seen pretty disgusting code with a big comment above it explaining what it does where if they had just named variables properly and split the code into decent functions the comment would have been needless. a classic case is something which looks like:

void HandleProcessing()

{

/// ... insert 1000 lines of code

}

which should be

void OptimiseMeshForRuntimeRendering()

{

RemoveDuplicateVertsFromVertexBuffer();

SplitIndexBuffersSoIndicesAre16Bits();

OptimiseIndexOrderingForCacheEffeciency();

PerformValidationChecks();

WriteOptimisedDataToDisk();

}

that code requires zero comments or documentation imo it tells you what it does and how it does it... sure its a crude example i just conjured and there is some bad practice there if you take it literally (what data am I throwing around? there should be function parameters...), but i'm not afraid to say that if you struggle to read code like this then you are just not very smart. maybe the concepts (index buffer, cache) need explaining, but thats not what comments are for thats for Google, Wikipedia, hardware and library specifications and generally just knowing enough to be competent in your domain.

comments i like are this:

void OptimiseIndexOrderingForCacheEffeciency()

{

/// use the k-cache optimisation algorithm, this has been measured to work on test1.mesh only

// imagine code here...

}

what i never want is a huge blob of comment explaining the algorithm and burying the fact that its effectiveness in this scenario has only been measured in a special case.

its shocking how many programmers are able to produce difficult to read 1000s of lines of code functions and forget the most basic principles of good, simple procedural programming, despite how familiar they may be with design patterns, OO or functional principles, CS theory, complexity bounds etc.

advice i constantly have to give and feel i never should: use functions. name them properly. use good variable names. don't write huge comments. refactoring is a lot quicker and easier than you imagine (and removes technical debt!). don't be afraid - source control will save you.

don't mistake the plethora of terrible programmers and lack of good example code for a sound principle being mythical...

EDIT: wtf is up with the formatting in this box? i see the help link now... but screw that i'm lazy