Tuesday, January 30, 2007
Getting Rid of Comments

Call me crazy right now before you even start reading this post just to get it out of the way.

I think it would be great if comments were removed from programming languages entirely. I think they do more harm then good and that if we removed the ability to use them a lot of us would have to be more disciplined when we code. Now, before you get all worked up hear me out. Here are my reasons for abolishing comments into programming language history.

1: If you couldn't use comments in a programming language you wouldn't get people admitting that they don't know what they are doing like this.

2: Comments are a code smell. If you couldn't use them you would have to explain what you are doing in a method name or with your code. 

3: TODOs are more often than not forgotten and rot inside the code. Maybe a TODO is better off as a story. Do people really need to know that you "hacked" something to make it work?

4: No one deletes commented out code, if you couldn't use them code would be a lot cleaner.

5: Comments are a way to temporarily get your code to compile but does it really need to compile or do you just need to write a test and some functionality that isn't there yet?

I would like to hear some arguments for keeping comments in programming languages. If not lets get rid of them! Viva Le Revolution!

Programming
Tuesday, January 30, 2007 8:06:32 PM (GMT Standard Time, UTC+00:00)  #    Comments [7]  | 
Tuesday, January 30, 2007 8:50:20 PM (GMT Standard Time, UTC+00:00)
I agree with what you say, but there is one place that comments are exceedingly valuable. If you are creating an API for any consumer (internal or external) having the documentation (XML comments) right in the code provides you with a known location of reference and a certain amount of compiler checking. Although you are right that comments in code usually indicate a smell of some level, the are an invaluable tool for producing outward facing documentation.
Donald Belcham
Tuesday, January 30, 2007 9:53:08 PM (GMT Standard Time, UTC+00:00)
But for that you use a special type of comment. If you left the XML comments in for the sole purpose of API documentation it may still be valuable but couldn't you just generate documentation off of a well named method? GhostDoc does a good job of it.
Steven R
Tuesday, January 30, 2007 10:42:48 PM (GMT Standard Time, UTC+00:00)
My argument for having comments is to explain purpose. Not "what does this function do" but more along the lines of..."why is this function here, what decisions led to its creation". It's hard to explain such high level information with just the name of the method.

That way, when things have to change, you can look at the comments when in doubt.
Mack D. Male
Tuesday, January 30, 2007 11:18:59 PM (GMT Standard Time, UTC+00:00)
I agree with your points, but not your conclusions. I think that comments are like code, and need to be maintained according. This means updating comments, changing them, and removing the TODO's when they're done, etc. Because most programmers don't know how to comment doesn't mean that you should abandon comments period.
Tom Opgenorth
Wednesday, January 31, 2007 12:28:51 AM (GMT Standard Time, UTC+00:00)
I'll always comment. If you take them out of the language, I'll invent a hack to put them back in. The main reason has already been mentioned by Mack D. Male. There are many cases when something could be done "more efficiently" or just plain differently. It's nice to see that if something looks a little out there, the developer actually did put some thought into it. Maybe there was a bug that occurred when printing to some obscure printer and someone added a few lines to fix that. The next person to come along may see those and yank them out with a "WTF is this for?"

Plus, I've always like the gestalt of comments (especially XML comments) to break up my code.

Comments aren't bad. But there are crappy comments just like there is crappy code. Best to know which you're writing.
The Coding Hillbilly
Wednesday, January 31, 2007 2:21:10 AM (GMT Standard Time, UTC+00:00)
On the point of no one ever deletes commented code, I always delete it. That is what source safe is for. If I need that code I can always roll back or do a diff. Granted it is sometimes hard to remember the point in which the comment was still in the code but for every commented out block I have deleted (and there has been a lot) I have never had to go back and do a rollback (results may vary).

I do hate abuse of comments but I have found that they can be useful as other people have mentioned.
Dave
Wednesday, January 31, 2007 6:21:02 PM (GMT Standard Time, UTC+00:00)
I would agree with the removal of comments. Actually if you have good unit test then that should be all the "comments" you need. The passing tests are enough to describe what a public function is doing. If some piece of code is too difficult to understand then it should be refactored to make it simple. Then everyone can understand it.
Anand Narayan
Comments are closed.

Theme design by Jelle Druyts

Pick a theme: