[buffportion]

>You're almost certainly not succeeding

You seem pretty convinced, so I don't have high hopes of changing your mind with a post on an internet forum, but in my experience most comments can be replaced by clearer names, better abstractions and better tests. The ones that can't tend to be about the "why" rather than the "what".

>Unless your section of the industry has no interest whatsoever in maintainability[...]

My primary motivation is maintainability, and your claims to the contrary come across as pretty condescending.

[flatline3]

> My primary motivation is maintainability, and your claims to the contrary come across as pretty condescending.

It's simple frustration with ego-based arguments from programmers that ultimately results in poor code bases.

Ego-based programming arguments are predicated on the idea that those that fail to deliver clarity must simply not be smart, wise enough, or skilled enough -- whereas with just a sufficient level of intelligence and skill and wisdom, one can produce lofty, comprehensible, elegant code.

If there's one constant I've found in my career, it's that everyone is dumber than they think, and everyone screws up. The ONLY thing that produces high quality code is careful attention to detail and slavish devotion to documenting and testing.

It's no different than any other pursuit; even a master carpenter will draw up plans, follow them, and measure twice (or three times). To think that one is smart enough to write perfectly literate code is foolish, and to force your future maintainers to deal with your uncommented code is to foist the costs of your short-term decisions onto them.

[einhverfr]

Comments in the body of a function should never be necessary for maintenance. The most unmaintainable code I have ever had the displeasure of working with was code which either had no comments or documentation or code with sparse documentation and LOTS of code comments.

If comments are necessary for maintainability, a simple solution is to flag the comment with a FIXME tag so that the next guy reads the comment and realizes that a section of code is unclear and should be looked at with extra care.

That isn't to say I am against code commenting. I find that when I follow my own code commenting practices and try hard to avoid using comments to explain code, I still use them frequently, probably more frequently than average. I am just saying the purpose needs to be clearly thought out.

In my view, the most important thing is interface documentation. This is a promise to the programmer, and it forms the basis of what you might think of as a development contract. You write your code this way, call the function this way, and you will get a certain return result. To a maintenance programmer, then, the question is whether the code works and by "works" I mean whether it fulfils its part of the contract by implementing what the comments promise. If a caller is requiring a corner case, then that can either be added to the documenting comments (i.e. adding to the promise) or the caller can be changed. So these comments are of vital importance and I see nobody arguing against them.

But within a function body things are different. Comments can be helpful here for collaboration and future development (and a subset of this is maintenance, but if you mind the rest this will take care of itself). A good maintenance programmer knows when to read the comments. if the comments describe the code, a good maintenance programmer will ignore them all in order to focus on what the code is actually doing and whether it fits the API docs. Bad comments then hurt more than they help and this includes comments which needlessly describe what the code is doing.

On the other hand good comments are golden and these either flag potential issues for the programmer (# BE CAREFUL OF SQL INJECTION HERE BECAUSE WE CAN'T USE PARAMETERIZED QUERIES!) organize code (# variable declarations) or add footnotes so that it is clear why a given choice was made (# RFC XYZ specifies a max timeout of 120 seconds).

The hostility is not to comments in code. The hostility is to a certain common practice, whereby comments duplicate code. There is no case where this makes sense without flagging the issue to a future programmer and noting that a rewrite is in order.