> The counterargument is that code should be self-documenting. If code is complicated enough to need comments, refactor it. Behavior should be obvious from func

> The counterargument is that code should be self-documenting. If code is complicated enough to need comments, refactor it. Behavior should be obvious from function and variable names. If you can't say what a method does in its name, it's too big. The best code transcends the need for comments. I used to believe that too, but I now believe that that point-of-view only addresses the accidental complexities of reading code. Don't get me wrong, descriptive function and variable names are great and make understanding code much easier. But I think it misses the forest (program structure) for the trees (functions). Where I get off that train is when trying to understand a program's structure. How do the modules decompose the problem being solved? Why was it designed a certain way? There's usually a combination of technical and domain knowledge that influenced the design. Sometimes, there's a philosophy that needs to be shared by the whole team to work effectively. I need to know all of that in order to effectively extend the program. There are also times (though less common) that I believe comments are needed to understand even the most clearly-written functions. This is usually when one needs background knowledge to understand the function. For example, a mathematical derivation isn't obvious when you're staring at a line of trig functions. At the very least, code like that needs a reference to a Wikipedia article or a book.