When I download something, the first thing I look for is comments. No matter how clever or elegant the code is, nothing 10,000 lines long can ever be so self-evident that you don't need comments.
Especially if the algorithm is particularly clever, it can be relying on some subtlety that will be entirely missed without a good long comment. Modifying such code is dangerous.
One of the reasons people like Knuth's approach so much is that he puts the comments first, conceptually. The code is essentially embedded in a great long comment that describes everything that's happening. The code is just there to distill the essence of the algorithm into a form a stupid machine can understand. If the machines were a bit smarter, they would be able to run the program by reading the comments and executing them!
Code with no comments is not a sign that the author understands his code so well that he doesn't need them. It is a sign that the programmer is lazy, sloppy, and doesn't care whether or not his code is maintainable.
I just can't emphasize this point enough: for Open Source projects commenting is even more important than code. A large faceless company can get away with releasing products built on hundreds of thousands of lines of uncommented code, because they have external documentation, and can afford to spend thousands of dollars training new programmers. But if you want other people to even look at your code, you have to help them understand it. People making patches to code they don't fully grok are just going to make a mess.
Good commenting style is as difficult to develop as good coding practices (the two really go hand in hand). Mental discipline (did you ever say to yourself "I'll go back and comment it later"? Did you?), clear exposition of an algorithm (no, the code is not a clear exposition -- remember code is CODE, it's meant for a stupid machine, not an intelligent human), maintainability, etc. Comments should be written in complete sentences wherever possible. Don't comment like this:
/*
* this comment
* is pretty
* but hard to format again
* when you change it
*/
Rather, write them like this:
/* This comment is a paragraph. Any text editor
can reformat this comment after you change it. */
Not everybody uses the same tools you do. Comments should be as easy to change as possible. If they aren't, people won't do it, and the comments can get out of synch with the code, which is even worse than no comment at all.
Languages without block quotes are very irritating in this respect.
So don't look for beautiful CODE, look for well written prose comments. THAT program will be more stable, easier to use, more functional, and a joy to work on.
The best code has lots of comments. (Score:5)
Especially if the algorithm is particularly clever, it can be relying on some subtlety that will be entirely missed without a good long comment. Modifying such code is dangerous.
One of the reasons people like Knuth's approach so much is that he puts the comments first, conceptually. The code is essentially embedded in a great long comment that describes everything that's happening. The code is just there to distill the essence of the algorithm into a form a stupid machine can understand. If the machines were a bit smarter, they would be able to run the program by reading the comments and executing them!
Code with no comments is not a sign that the author understands his code so well that he doesn't need them. It is a sign that the programmer is lazy, sloppy, and doesn't care whether or not his code is maintainable. I just can't emphasize this point enough: for Open Source projects commenting is even more important than code. A large faceless company can get away with releasing products built on hundreds of thousands of lines of uncommented code, because they have external documentation, and can afford to spend thousands of dollars training new programmers. But if you want other people to even look at your code, you have to help them understand it. People making patches to code they don't fully grok are just going to make a mess.
Good commenting style is as difficult to develop as good coding practices (the two really go hand in hand). Mental discipline (did you ever say to yourself "I'll go back and comment it later"? Did you?), clear exposition of an algorithm (no, the code is not a clear exposition -- remember code is CODE, it's meant for a stupid machine, not an intelligent human), maintainability, etc. Comments should be written in complete sentences wherever possible. Don't comment like this:
Rather, write them like this:Not everybody uses the same tools you do. Comments should be as easy to change as possible. If they aren't, people won't do it, and the comments can get out of synch with the code, which is even worse than no comment at all.
Languages without block quotes are very irritating in this respect.
So don't look for beautiful CODE, look for well written prose comments. THAT program will be more stable, easier to use, more functional, and a joy to work on.