commenting or documenting…

When I got interviewed, people tended to ask me, “Can you use Doxygen?”, “Can you use ‘some other document generator’?”.
Usually, when I am asked like that, it turned out that their documentation or whatever stuff they asked was not good in the company.

Commenting, or documenting in source files should be part of architecture, design or planning.
It’s not something you are to write after you implement something. It should be written before you start implementing something and while implementing.

What I mean is this. Commenting/Documenting is for maintainability or help for easier understanding of code.
If people make fun of you when you say “How bad it is! There is no comment!!”, then it’s Ok to treat them as non-professional people.
They will say “Real S/W engineers should be able to figure out without comment.”

Well.. they are only half-right. Sure. If you are a person who can think. Sure.. you can figure it out. However, just to use something and maintain, if you need to spend too much time, it’s not good. Commenting is to help that case. If it gives you an idea what the code part is for, you can get a pre-image to the code block. Then you can figure out things even quicker. Also, you can understand the original authors’ intention, suffering or odd situation they were in.

However, another very important reason for commenting is this.
It helps you to plan things better.
For example, even before writing, you can use your IDE/source code editor as a scratch paper like this.

void MyClass::doSomethingGreat( void )
// 1. Retrieve data from twitter

// 2. Check if there is user object in the response data

// 3. ...

Then, those commenting can plays very important role to aid you to organize your idea and split big task into small chunks.
You can get more rigid idea on what you are going to do. Sometimes by writing as such, something ambiguous can be clearer.
Also, after you write code, it can help you to locate interested portion of code quickly.
Then, it becomes great comment and documentation for itself. You don’t waste your time in writing comment/document. Your design time becomes your documenting time naturally.

Another very important point i would like to address is… Please use and pick terms others can use. Don’t use your own abbreviation and explain things really.

Here is a good example from twitcurl project.

* @method: twitCurl::mentionsGet
* @description: method to get mentions
* @input: sinceId - String specifying since id parameter

Especially take a lookat @input: sinceId line.
What is ‘sinceId’? that will be the question when you first confront the line.
Does “String specifying since id parameter”  really explain what sinceId is?
How about this?

* @method: twitCurl::timelineHomeGet
* @description: method to get home timeline
* @input: sinceId - the post ID for the last retrieved post.
*                                  Post with IDs after sinceID will to be retrieed

Isn’t that better? Anyway you should refer Twitter’s API documentation, but even without it, you can figure out what the sinceId means in that context.

I don’t count comment like the one in the mentionGet method.
You should not say you write comment if you write as shown in the mentionGet method.

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: