Thursday, May 1. 2008
The Futility of Comments
Trackbacks
Trackback specific URI for this entry
No Trackbacks
Comments
Display comments as
(Linear | Threaded)
Let me amend that a bit -
> Yes. Instead of writing comments, write code that doesn't need comments.
if possible
You can't always do this. It's usually once you have to go closer to the metal that you need comments. (I.e. "do this magic thing, since it improves cache coherency" is a rather common one in my field)
> Yes. Instead of writing comments, write code that doesn't need comments.
if possible
You can't always do this. It's usually once you have to go closer to the metal that you need comments. (I.e. "do this magic thing, since it improves cache coherency" is a rather common one in my field)
Very true. It is not always possible. As I said, "Sometimes a line or two is required to explain something not clear from context, but it's rare." Often it's because you're doing something that may not seem efficient or logical.
One example is using the Apache request object in mod_python. To get the user from an HTTP auth request, you have to call the function to decode the password first, before you can get the user (because that's the way the Apache API works). You don't want someone to come along later and reorder those statements, and then spend an hour trying to figure out why it doesn't work.
Another example is writing out cookies. The most natural idiom in Python would be a simple for loop over the keys of a dict, but since the spec requires the 'value=foo' part to be the first key/value pair, some extra logic is required. A simple comment alluding to the requirements of the spec is sufficient, and will keep someone from "optimizing" the code later and breaking things.
So, you're right: sometimes comments are required, but the more I program, and the clearer I try to make my code, the more I realize commenting code can be not only redundant, but distracting.
One example is using the Apache request object in mod_python. To get the user from an HTTP auth request, you have to call the function to decode the password first, before you can get the user (because that's the way the Apache API works). You don't want someone to come along later and reorder those statements, and then spend an hour trying to figure out why it doesn't work.
Another example is writing out cookies. The most natural idiom in Python would be a simple for loop over the keys of a dict, but since the spec requires the 'value=foo' part to be the first key/value pair, some extra logic is required. A simple comment alluding to the requirements of the spec is sufficient, and will keep someone from "optimizing" the code later and breaking things.
So, you're right: sometimes comments are required, but the more I program, and the clearer I try to make my code, the more I realize commenting code can be not only redundant, but distracting.
Our Links
Calendar
|
October '19 |
| Mon | Tue | Wed | Thu | Fri | Sat | Sun |
| 1 | 2 | 3 | 4 | 5 | 6 | |
| 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| 14 | 15 | 16 | 17 | 18 | 19 | 20 |
| 21 | 22 | 23 | 24 | 25 | 26 | 27 |
| 28 | 29 | 30 | 31 |
The Good Blogs
I'm giving this a trial run. Right now, I'm only promoting Tech, Business, Venture Capital, and Auto categories, so hopefully the content will be pretty clean. If you see something that would not be in line with my standards of "family friendly," please contact me at once, and send along the URL of the offending article.
Technorati
Archives
Syndicate This Blog
Powered by
