[buffportion]

> Anyone who advocates against comments is justifying laziness

That is a gross generalization. I do not, in general, comment my code (and I know and work with many other programmers who do not) but I go to great lengths to ensure that my code is easily understandable. Commenting is not the only way to communicate intent.

I suspect we work in different sections of the industry, but in my world, comments are often a red flag rather than a welcoming sight!

[flatline3]

> That is a gross generalization. I do not, in general, comment my code (and I know and work with many other programmers who do not) but I go to great lengths to ensure that my code is easily understandable.

You're almost certainly not succeeding, because unless you work with a language far more expressive than one I've seen previously, then your code can not express all the information I need to work on your code.

A complete lack of comments is on my top three list of "bad times ahead" warning signs when I inherit a codebase.

The other "bad times" warning flags are:

* A lack of documentation

* A lack of automated tests (integration, unit, or otherwise).

These three things can make or break maintainability on their own, and they also often serve as a proxy indicator for just how much thought an engineer put into fully understanding the invariants and edge-cases of the code they've written.

The hard part of writing comments, documentation, and tests is in understanding invariants and edge-cases. The easy part is writing down what you've understood.

> I suspect we work in different sections of the industry, but in my world, comments are often a red flag rather than a welcoming sight!

Unless your section of the industry has no interest whatsoever in maintainability, I'm not sure our respective sections are very different.

[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.

[einhverfr]

Well, I inherited a codebase where all comments fell into two groups:

1) Copyright notices and brief (1-2 line!) file-level descriptions at the top of each file and

2) Comments that the code needed to have in place in order to run properly... Delete the comments and things break. I am not kidding.

Oh, no documentation and no unit tests either. We started adding unit tests and found that things like number rounding failed.....

Years later we are still replacing the old code as fast as we can. The obvious things including braindead security issues, were just the absolute tip of the iceberg.

Nowadays I write my documentation first, then code, then at least some tests.

[mangler]

That's why you "Inherit a codebase", as opposed to "Build a codebase". People who maintain and people who build are... well... they're just different people. We do need them both, but, they are different. Which is why we need them both.

[flatline3]

I also build code rather large new products, too.

People that build with no regard for future maintainers are building code incorrectly.

It makes me happy when I hand off a code base and the receiving maintainer actually tells me that they appreciate how clear and understandable it is. That's a level of care I wish I always inherited.

Maintainers versus builders aren't different people -- that's just what intellectually lazy programmers tell themselves when they're making another mess for someone else to clean up.

[einhverfr]

I don't think that is necessarily the case outside a corporate environment. I inherited the SQL-Ledger codebase when we forked to LedgerSMB. Now I am using it as scaffolding to build a very nice, clean, powerful codebase in its place.

[einhverfr]

I do not, in general, comment my code (and I know and work with many other programmers who do not) but I go to great lengths to ensure that my code is easily understandable. Commenting is not the only way to communicate intent.

I agree that commenting is not the only way to communicate intent.

I don't know what you mean by commenting code though. I find in general that the people who treat commenting as a last resort, and look for every other method to clarify code first, tend to also have some of the highest comment to code ratios, as well as the best comments.

This was driven home to me recently when I wrote some PHP classes for interfacing with LedgerSMB. I checked them into github and added the project to Ohloh, and was stunned when it said I had as many comments as code. But virtually all of these were interface documentation.