Saturday, October 30, 2004

Code Lies as Much as Comments Do > Comments lie. Code doesn't. This sentiment is used as justification for having very few if any comments in your code. I just don't buy it for many reasons. Code lies like a dog under a shade tree in summer. Code lies because the variable names, class names, and method names don't match what the code does. People will use lame names or they will insert new code into a method or new methods into a class that change the nature of the thing. That is a lie in my book. And it happens all the time. You may say use good names and you won't have a problem. I agree to a large extent. But i can't make people program well no more than i can make people comment well. If you can accept that people must use good names then you can also accept that people must make good comments. Trust cuts both ways. And the lie continues because a name is flat. It relates only to one aspect of a thing. Things are multidemensional and can't be mapped meaningfully to a single name in all its contexts. To the government i am social security number. To my dog i am a pat and a meal. To those i disagree with i am an idiot. To my doctor i am a series of stats. What is my name? I have been mislead by comments, but have been helped far more than i have been misled, so that's a win in my book. I have yet to see any of this code that is self-documenting so i am unwilling to do away with comments on that assumption. XP assumes a continuous chain of oral tradition to make the use of comments less necessary. Perhaps on an XP project this make sense. But much of my experience is in large distributed teams with lots of churn so i don't think this is a generally applicable rule to do away with comments. No more than i would get rid of jails everywhere just because there is almost no crime in my house. Code without good package documentation, good class documentation, and good method documentation is torture. I dred to trying recreate the entirity of something in my mind. Such a person usually left me with no information as to why they did anything. They don't indicate any alternatives and why one shouldn't use them. They don't indicate how this smaller chunk fits into the larger chunks that use it. They don't think like me so most of their decisions are a mystery and their names are usually empty. They will do something odd for some reason i can't quite grasp. Now there is a lot of truth in "Comments lie. Code doesn't." Developers need to strive to make good clear code. It's just that they usually don't because it is hard. Often they can explain themselves in text better than they can in the strict confines of a programming language. What i want answered for my are the questions i'll have when reading the code. Why? What? Where? Who? When? The code is the result of a long thought process and i can't recover that thought process from code alone. A narrative is needed. Code boils down to a very limited set of nouns, adjectives, and verbs. The story is gone. The motivation is gone. The experience is gone. The trials are gone. The conversations with all the people who helped shape the code are gone. Code is like a story story that says: "She jumped off the bridge and died." There's a lot more to it and we know it. I need good comments to help me with all that so i can continue the story. Comments like: i++; // increment i suck and are a waste of time and are worse than useless. I don't mean the kind of comments where we have a useless line by each method argument. There are a lot of comments like that in code. Those i don't want or need. But those aren't the comments i am talking about. comment[] 3:39:40 PM

© Copyright 2006 todd hoff. Last update: 7/11/2006; 1:11:01 PM.