Have you ever heard the common excuse for programmers not commenting their code:
The problem with comments is they lie. The code changes (as code tends to do) and the comments are never updated which leaves them inaccurate. The code always tells you what it is doing. So you are better off not writing comments since it just takes more time and only confuses and misleads anyone supporting your code in the future.
Seems like a brilliant argument against comments, doesn't it? Why go through the extra work of writing comments if they are only going to confuse future developers, including yourself? One might be convinced that comment writing was a bad idea and no-one should do it.
One might think that, but only until they start to think.
Having supported both commented and uncommented code, I can speak from experience that any comments is 100x better then no comments. Sure, I have seen comments that are out of date, extremely vague, or more verbose then the code it was commenting on, but I still prefer any of that to the alternative of no comments.
Saying the problem with comments is they get out of date with the code changes is like saying the problem with source code is it gets syntax errors when you edit it. If you think about it, over 90% of the time you are editing a piece of source code it has a syntax error and will not compile. If you are writing a line of C# code that is 40 characters long, it will have a syntax error for the first 39 characters, and only be syntactically correct once you put that semicolon in place. Even then it might still be incorrect. Don't forget your curly brackets!
By that same notion you could say that the problem with software developers is they introduce errors into the source code, which we do. Working on a piece of code is like open heart surgery. We cut the patient open, rip a lot of stuff out, move things around, and then connect things back up again (not being a surgeon I have no idea if this is what surgery is like, but it works for my analogy). The very first thing we do is break the code. The program will not work again until we finish with what we are doing. Sure, an agile or iterative approach means the program spends less time in a broken state, but the fact is, every time we touch a piece of previously working code we break the code before we make it work again.
Now you may argue that this is a poor analogy since a good developer always fixes the code they start on. Well, that is my point exactly. If you come to a piece of code that has a comment on it, and you change the code so the comment is no longer accurate, then your job is not done. Just like you put a semicolon at the end of your lines, making sure the code it syntactically correct and operates as expected, a good developer also updates the comments and adds new ones outlining the changes they made.
I don't claim perfection in this area, but I certainly advocate improvement instead of making excuses for laziness. How about you?
Subject Tags: [Programming] [Software] [Developers] [Code Comments] [Source Code] [Laziness] [Comments]
3 comments:
I completely agree with you. I used to work with two chaps who were allergic to commenting code and it was a nightmare fixing what they’d written after they’d left. So I know from first experience, that it’s essential. Part of being a good developer is commenting what you've written!
The two highlighted bits in the penultimate paragraph sum it up nicely. If you're modifying your code or someone else’s, adjust the comments to match.
I too agree, especially with the last statement equating lack of comments with laziness! Sometimes I am amazed at the lengths people go for self-justification.
How do you measure how many comments in your codebase are correct? How do you test them?
Why not spend the time spent writing comments to create a test that illustrates how the code works AND keeps it pinned in place for the next developer to come along?
(This is by no means perfect reasoning: tests, whether unit or otherwise, are also "code", and have as much need for "comments" as the target code... but at least tests tend to be written in "the language of assertion.")
Post a Comment