[btilly]

I've just read this whole thread.

flatline3, I can tell you flat out that you are wrong. There are plenty of senior level programmers that are quite deserving of the name who deliberately comment very lightly if at all. There are also plenty of senior level programmers who think that verbose commenting should be required of everyone.

I have experienced both styles, both in forms that are implemented well and implemented poorly. I have read arguments for both sides. I have found that either can work well, and either can work out horribly. (Though attempting both at once is very much not recommended.)

Personally I prefer to work with (and write) code that avoids comments wherever I have any reasonable alternative (clear variable names, calls to descriptively named functions, error checks with error messages that make it clear what I was trying to do, etc). However when all other alternatives fail, I do not hesitate to comment.

The most important case where there is no reasonable alternative is in descriptions of an API. The code that is there is how it happens to work right now. If you want to know what you can rely on to remain true in the future, read the documentation. Anything not documented is not part of the API, and you should be prepared to find it changed in the next release.

[flatline3]

> There are plenty of senior level programmers that are quite deserving of the name who deliberately comment very lightly if at all.

Senior in name (and possibly years) only. I've spent enough years cleaning up messes to know that master programmers:

- Design carefully - Comment liberally - Test thoroughly

Thus they produce clean, well documented, understandable code. Skipping any part of that list is foisting delaying the cost for a much larger later reckoning of some poor future persons.

You might get away without commenting, but you're not doing anyone any favors. Skip all three and you're incurring significant technical debt.

I have no respect for programmers that think their sole job is to write code (no matter how "descriptive" it is).

> The most important case where there is no reasonable alternative is in descriptions of an API. The code that is there is how it happens to work right now. If you want to know what you can rely on to remain true in the future, read the documentation. Anything not documented is not part of the API, and you should be prepared to find it changed in the next release.

All functions are API. Some is mutable, because you can check and modify all callers. Some is immutable, because you can't.

It all needs to be documented, and the cost for not doing so can scale exponentially as a code base grows.

[btilly]

Ah, the "no true Scotsman" fallacy. No matter what someone has accomplished, no matter how much experience they have, you're the judge of whether they are really a senior programmer. And all who do not meet your standards are not senior programmers and are therefore not data points counter to your position.

Read the source code for Arc. You'll find that Paul Graham is not a senior programmer by your definition. Read the source code to some of Damian Conway's modules. You'll find that Damian Conway is not a senior programmer by your definition (though his stuff does usually come with wonderful documentation). There are plenty of other examples of talented programmers in your books are not senior.

From where I sit, I know nothing about you other than your account is about 2 months old and this discussion. In particular I know nothing of what you've done. However people that I respect a heck of a lot more than you have defended very light commenting styles. I've seen it work. I've also seen it fail. Ditto for heavy commenting styles.

Therefore, based on my own experience, I'm going to say that it is complex, with valid arguments on both sides. Which puts me on about the same page as Steve McConnell's book Code Complete.

But I'm going to go further. The downsides of a comment heavy style have to do with the possibilities of the comments being misleading. People have to be very, very careful to maintain comments along with the code. Based on what I've seen, I would personally not trust any team of programmers to do this reliably without having careful code review processes. If you have this careful code review process to alleviate the potential issues with commenting, I would advocate a much heavier commenting style.

But there is one line that is very important that explains a lot of the difference:

It all needs to be documented, and the cost for not doing so can scale exponentially as a code base grows.

There are a lot of problems that scale non-linearly as a code base grows. There are two possible responses to this. The first is to try to create procedures to alleviate the problems that are intrinsic to growing code bases. The other is to maximize what can be done without growing your code base.

There is a fascinating data point on this that is cited in Software Estimation: Demystifying The Black Art. For projects of a fixed size (about 50k lines of code) there is a graph based on real world estimates of months to completion versus team size. Initially as teams grow, calendar months fall. Then the graph bottoms out with teams of 6-8 people. Then it starts to rise. And then falls again. It isn't until you get to teams of about 20 people that calendar months fall to the same level. (Given that lines of code was the measurement, it is likely that the productivity of a 20 person team was overstated.) And then they start to fall further.

If your experience is mostly on teams of 12+ people, your observations about software development will be very, very different than if your experience is mostly on teams of less than 8 people. What works for those types of teams teams is very, very different. And given the huge productivity valley between small teams and large teams, there are a lot of problem areas where the right approach is to maximize what can be done by small teams, rather than to figure out how to build procedures to scale to (the now inevitably necessary) larger teams and code bases.

(If your experience is with larger teams, your first encounter with the potential productivity on small teams can come as a shock.)