3 ms·

Not sure I like #17 (http://programmer.97things.oreilly.com/wiki/index.php/Comment_Only_What_the_Code_Cannot_Say http://programmer.97things.oreilly.com/wiki/ind

by NKCSS 13y ago

Not sure I like #17 (http://programmer.97things.oreilly.com/wiki/index.php/Comment_Only_What_the_Code_Cannot_Say http://programmer.97things.oreilly.com/wiki/index.php/Commen... ). While I would prefer working this way, my colleagues probably won't. Reading code you haven't written yourself is tough and time consuming. If the code is accompanied by the 'natural language explanation' of the code, you get into the code quicker. The downside to this is making sure they stay up2date, which was probably why the author wrote the section.

barking 13y ago
That's why it's worth having short methods that do one thing and are meaningfully named. And from a personal point of view I'd prefer several lines containing short expressions that are then assigned to meaningfully named variables etc, rather than 1 really long hard to parse line of code.
- NKCSS 13y ago
  Yeah, nothing wrong with that, and if you do have a longer/more complex equation (like a C# LinqToSql where statement), you can always make it formatted multi-lined instead of in-line to improve readability. My point was mostly about not using comments that describe the code.
- reginaldjcooper 13y ago
  This is how I originally felt a few years ago doing Ruby, and I have tried to make all my code human-readable since.
scrabble 13y ago
Occasionally I get asked to add comments in for standard language features that others might not know. That to me seems like a waste of time. I have no problem emailing people to let them know of a feature they may not be aware of, but now that language feature is documented right there in our code base.
base698 13y ago
Comments also frequently repeat what is obvious and don't illuminate the bigger picture. Ie a Pythagorean theorem function would have a comment about squaring numbers and adding them instead of for what it's used in practice.
- ygra 13y ago
  By extension that's something that often goes for documentation comments (Javadoc, doxygen, etc.). When reading those I find it not really useful to learn that the frobFoo(Foo f) method frobs a foo and leaving the use of that method, what frobbing is and what a Foo is out of that documentation. Figuring out how to use something larger is much easier when classes come accompanied by usage samples and some notes about how they fit into the larger picture.
crazygringo 13y ago
It says: > Any shortfall between what you can express in code and what you would like to express in total becomes a plausible candidate for a useful comment. This is a good way of looking at it... as long as you remember that this shortfall is often gigantic, and usually includes why this approach is being used instead of other techniques (which may have been used and abandoned for good reason). Code does not exist in a vacuum. You should write code not just to compile, but to be read by others. And many times, the actual code might be only 30% of the important stuff. A good project may very well be 2/3 comments, 1/3 code, because it should include the reasoning behind coding decisions, which is often quite complex, but crucial to understanding why the code is written as is, and to understanding how to properly extend it. Without that kind of documentation, you're doing a tremendous disservice to future programmers who seek to maintain or add to the code -- or to yourself, often times, when you pick up code you wrote yourself two years ago.

by NKCSS 13y ago

barking 13y ago

That's why it's worth having short methods that do one thing and are meaningfully named. And from a personal point of view I'd prefer several lines containing short expressions that are then assigned to meaningfully named variables etc, rather than 1 really long hard to parse line of code.

NKCSS 13y ago
Yeah, nothing wrong with that, and if you do have a longer/more complex equation (like a C# LinqToSql where statement), you can always make it formatted multi-lined instead of in-line to improve readability. My point was mostly about not using comments that describe the code.
reginaldjcooper 13y ago
This is how I originally felt a few years ago doing Ruby, and I have tried to make all my code human-readable since.

scrabble 13y ago

Occasionally I get asked to add comments in for standard language features that others might not know. That to me seems like a waste of time. I have no problem emailing people to let them know of a feature they may not be aware of, but now that language feature is documented right there in our code base.

base698 13y ago

Comments also frequently repeat what is obvious and don't illuminate the bigger picture. Ie a Pythagorean theorem function would have a comment about squaring numbers and adding them instead of for what it's used in practice.

ygra 13y ago
By extension that's something that often goes for documentation comments (Javadoc, doxygen, etc.). When reading those I find it not really useful to learn that the frobFoo(Foo f) method frobs a foo and leaving the use of that method, what frobbing is and what a Foo is out of that documentation. Figuring out how to use something larger is much easier when classes come accompanied by usage samples and some notes about how they fit into the larger picture.

crazygringo 13y ago

It says: > Any shortfall between what you can express in code and what you would like to express in total becomes a plausible candidate for a useful comment. This is a good way of looking at it... as long as you remember that this shortfall is often gigantic, and usually includes why this approach is being used instead of other techniques (which may have been used and abandoned for good reason). Code does not exist in a vacuum. You should write code not just to compile, but to be read by others. And many times, the actual code might be only 30% of the important stuff. A good project may very well be 2/3 comments, 1/3 code, because it should include the reasoning behind coding decisions, which is often quite complex, but crucial to understanding why the code is written as is, and to understanding how to properly extend it. Without that kind of documentation, you're doing a tremendous disservice to future programmers who seek to maintain or add to the code -- or to yourself, often times, when you pick up code you wrote yourself two years ago.