During today’s Sydney geek coffee (Wed 1pm @ Jet Cafe each week) the topic of comments was discussed. I’ve heard all manner of reasons why you should, and interestingly, shouldn’t comment code. Anyhow here are a couple of reasons why you shouldn’t comment code:
- It makes the code more unreadable – Just because you’re a super geek and can read code better than English, doesn’t mean the rest of us are. With Visual Studio font formatting you could just modify the comment font colour so that it doesn’t stand out as much
Personally I would prefer to make them more obtrusive so that I’m forced to read the comments before launching into the code
- Code should be self describing – Well yes, one of my reasons for being pro-VB is that I find it more explicit and easier to read. Having said that, comments shouldn’t be “check this variable isn’t nothing” for a statement “if myVariable isnot nothing then” – comments should be about describing how what you are doing fits into the bigger picture, or in the case of work arounds/fixes etc why you have chosen to do something a particular way.
- Comments quickly become out of date, so why bother – Now this is an interesting one. My initial thoughts are that it is likely to be the same people who don’t update comments, that don’t write them in the first place. Thinking about this problem a little more I thought of how Word deals with comments.
Now wouldn’t it be cool if we could have comments for specific bits of code
Thinking about this in terms of how it would exist in the code file I came up with some possibilities but none of them were very elegant given the way comments are integrated into the languages. Any thought as to how either C# or VB.NET could support this style of commenting?
Why would this help this scenario – well if you have comments that are actually tied to a line or a portion of a line, Visual Studio could indicate that the comment should be updated whenever the line changes, thus prompting the developer to update the comment (no guarantees they will of course)