[TimothyFitz]

Actually, that's EXACTLY the case I had in mind. Obviously I couldn't put a 50 line function with weird data structures in my blog post, or it would be unreadable. But the point is that comments for that function are bad! They'll rot if you ever change the function or the assumptions at all. Instead, you should break the 50-line function up into smaller functions, and add assertions and test cases for all of those "magic-lik assumptions." Then get in the habit of reading tests first. Now your code-as-comments will never rot.

[drobilla]

No offence, but this is incredibly naïve, and it's kind of obviously an opinion that simply stems from working on things that just aren't that conceptually complicated. Some things are actually conceptually complicated, and the why is not at all obvious from the what, no matter how finely you slice the what. Code, inherently, describes what. A sparse set of higher level proper sentence comments describing the purpose of the overall goal for the next part is practically required to make code like this actually comprehensible. For some things, something approaching Literate Programming is best, which is nearly the polar opposite of "comments are bad".

Implementing an advanced data structure is a good example of this. Things that took theoreticians some time to discover, and write/publish in a paper, are not things a random programmer is just going to inherently know from a completely uncommented implementation.

Extrapolating "all comments are bad" from a few examples of pointless comments on mind-numbingly simple and obvious code (which are indeed bad) is silly.

[barrkel]

OK. But the algorithm is over a 1000 lines split up into perhaps 50 20-line functions, and it's mysterious how the whole works by looking at the parts.

I have one particular piece of code, that I wrote, in mind. It was to implement anonymous methods in the Delphi compiler. Given an AST for a method from the parser, it had to rewrite the tree to turn captured local variable references into field accesses on a heap-allocated stack frame, turn anonymous methods into methods on this heap-allocated stack frame, and all while minimizing the number of passes over the tree. And this has to work recursively, which adds a surprising number of wrinkles about the ordering in which you can do things.

So for example any given pass may be building up accounting data needed by later passes. This is somewhat mysterious, because it seems like busywork; and why is it doing this here? Why not fold one pass into another? Why not move work between passes? Well, the subtle ordering problems are not clear at all when you're looking at things at the function level. You can only understand the pieces when you already understand the whole.

And this is why there is a very long comment block describing how this stuff works. Because figuring it out by reading the code is too expensive.

(That ~1000 lines of code took perhaps 4 months to write; having to integrate with rest of a large complex codebase adds countless more wrinkles.)

[katbyte]

I've worked on code like that, and i'm sorry but i would rather read a 50 (or even couple 100 if appropriate) line function implementing specific functionality that is well written and documented with comments then have that critical information split up into a multiple functions and test cases spread out over multiple files. Sometimes functionality belongs together and it would be far more difficult to get that all that disjointed information into coherent mental model.

Not to mention how test cases and function names would just not cut it for explaining things like why the current implantation was chosen over more obvious, simpler ones, why the magic like assumptions are necessary and documenting the bugs/quirks in the underlying library or framework that are not obvious. Things like why call object.SetValue() instead of property object.value = x? Or Free memory from this call here, but not here, because the framework takes care of it.

I prefer commented code, even if it is over commented, because at the very least it is a way for the last programmer to explain why she implemented things the way she did.

[kamjam]

But the point is that comments for that function are bad! They'll rot if you ever change the function or the assumptions at all

Do you leave unused functions in your code when you refactor? No. So refactor your comments, or delete them if they are no longer applicable, when you refactor your code.

I have been saved many times by comments in my own code, because you know I work on a lot of stuff, sometimes coming back to it after years and I hope I have developed as a coder and so my mindset is now different and a lot of the time I do wonder WTF was I doing here!

This is the opposite of your post http://tech.collectedit.com/post/2012/11/12/Comment-your-dam... which I tend to agree with a lot more.

Your code tells me what you did. Your comments tell me what you intended. Help me out. Help your future self out!