http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.htm... ?

This is interesting, and not something I'd consciously thought about before, but quite often I will go back after I've finished something and add some white space and (sometimes quite thorough) comments to the code I've written. I especially do this with open source code that I plan to release.

My reason for doing this is that I want to make it clear to whoever ends up maintaining the code after I've left the project. I have no idea what their skill level might be and getting up to speed on someone else's code can be tedious. Apparently this also makes me look like a less-skilled developer?

I've spent quite a bit of time working on systems that became untenable and had to be partially re-written or completely re-written. The result is the original code was either a baseline or a reference. I will say, without a doubt, comments are a code smell. Any comments.

If you write a piece of code and think you need to comment it because it won't be clear for the next guy. It is good at best.

Furthermore, comments rarely help. They are written while you are in complete comprehension of the program or that part of it. The next person (assuming the comment is something they are using to figure it out) won't be.

That said, if you can do nothing to improve the quality because of time, lack of interest or necessary complexity. At least, make your best effort to comment what it does. Appreciating the fact that this is a minimal quality improvement action. Sometimes it is just a piece of code that has to be optimized, explain why so the next guy doesn't refactor/re-write it.

Thanks very much for the perspective.

Personally, I think (and judging from the reactions of the people I work with, they seem to agree) that my code is solid; efficient, well organized, logical, descriptive, but not too verbose, etc.

Your comment has made me go back and re-evaluate some things, though, and look over some of those comments - and it was at that point that I realized that a lot of them are superfluous and serve no real purpose other than to restate what's already clear in the code. Others in the particular code I was looking at were about things like UI customization and how one might extend the existing code in order to do that, which more correctly belongs in the documentation (and would have wound up there eventually).

Again, most of this had been in open source PHP/Ruby/JavaScript code, where I'd assumed that the average tinkerer wouldn't be as well-versed in the language, but now that I think about it, if they're not, they need to learn before tinkering, rather than me trying to "dumb it down" to their level, which probably just invites disaster on multiple fronts.

So in my attempts to make things tidy and easy for the next person to come along, I was instead just injecting garbage that didn't need to be there.

Which kind of sucks to realize, but on the other hand, I suppose it's better than realizing you've been commenting the hell out of everything because the code actually doesn't make sense without the comments.

I am glad the comment (heh) helped you in some way.

I have done research programming into new algorithms in a pretty exotic area. Those sorts of algorithms are not comprehensible without documentation, ie, comments.

OTOH, outside of that, I would agree that comments have a limited use.

As a corollary, I can tell a code review session has reached its end when we start debating coding style, which I find happens about 2 minutes after we agree to talk about coding style at all. I've never found the intricacies of variable naming helpful, though I've participating in a number of discussions on the subject.

Code style guidelines are just that: guidelines. Being able to work in a group with a broad range of coders (from inexperienced to hyper-genius) is a highly useful skill for a coder.

Being able to communicate about the project to management, customers, and online is an even greater skill.