Tuesday, June 28, 2011

Yes, comments are important!

I'm currently a little bit stressed and won't have time for much development the next few weeks, because as I already told you, my final exam for my bachelor degree is in almost two weeks. There is much to do and study, so don't expect any updates for my apps until after that exam.
Nevertheless I'll try posting on a regularly basis and today's entry is about comments – more precisely comments in source code.
Comments are something very important. Every developer should know that, but not everybody uses them as often as needed – I'm no exception.

First of all!
You don't have to comment each and every line of your code, but those parts, that are hard to understand, when reading them. Don't make excuses – even if those parts were hard to write, they don't have to be hard to understand.
But not only code parts that are hard to understand should be described. I think at least every public method should be documented, because it's very likely that someone will call it. Even if you work alone on your projects and don't release them under an Open Source license. Maybe sometime you change your mind and let someone help you: that's when it's too late, because writing comments for a medium to large project is a pain in the ***.

Now how should you write comments?
The way the coding conventions for the programming language describe them. Don't be ignorant! Those conventions will help you, because there are many tools that allow you to automatically generate API-documentation.

So why don't I always comment my source code?
As you maybe noticed: the source code from the Geocaching Helper for HP TouchPad doesn't include comments. That's because I wanted to finish the project as quickly as possible and I knew that there'll be not many files. In this case, documentation can wait until after my final exam ;)
If you knew the source code I wrote during my internship, you would think I'm crazy: There is not one single method that isn't documented (not even trivial ones)! Any why? Because I want the company to know what every method does, without reading a single line of source code.

One last thing!
Some people also write comments for blocks (see the example below). Please don't. I have often seen those comments and never understood why they should be useful. Some people argue that they make it easier to see block end and know where they belong. I don't think so. They are only overhead in writing and consume more toner/ink when printed.

if (writeComments) {
} // if

I hope you liked this entry. If you disagree, write a comment below or contact me. IF you agree, also write a comment ;)

Labels: , ,


Post a Comment

Subscribe to Post Comments [Atom]

Links to this post:

Create a Link

<< Home