comments
Comments about the comments:
Comments are part of every programming language. You’ll find them in every language whether its Assembly language, C, C++ or a scripting language. Call them as REMarks (in GWBASIC), Note (in COBOL) or just plain /* */ notation, they serve a common and a very important purpose. They provide a means to programmer of telling what was in his mind while writing the code.
But the saddest part of the story is that the comments are kept aside in the race to meet the dead-lines on time. A programmer often considers commenting a waste of time and effort on his part.
This article will try to explore the questions surrounding comments such as:
1. How much time a programmer should spend on comments?
2. How much help comments would give?
3. At what time of development commenting would be helpful?
4. To whom commenting would be helpful?
Question about the questions:
“The important thing is not to stop asking questions” - Albert Einstein.
You must have a reason, a logical reason for everything. So let’s get started to find that reason.
My experience:
From quite sometime I have been coding in C#.NET. C and C# share one thing common with many other languages, inline comment support. A project in coding phase for about 6 months with a team-size of 10 developers can reach anything up to 100,000 line of code (obviously this is not a great unit of measurement, but I don’t have another). One may ask, “I am writing code, it’s my code, I know what variables I have declared at the beginning of the loop”. Well, cool, but you are not planning to take the code with you to the grave. The point is that things change and someone else would require changing your code in future or you might be providing enhancements in someone else’s code. In this case the programmer would find himself in lost in some-one else’s code and at that time only two things can save him caffeine and comments. In either case you will be looking, for example, only the 1/50th of the total code. Comments in this would be of some help but rests are of no use. Questions, No, we can’t point out those marks in development phase.
Then what’s good:
Most commercial projects are often developed in repetitive patters. Most of them may include one or more of following subsystems: File Saving- retrieving, file manipulation, GUI and displays, Database operations, etc. Comments like: “execute the SQL Query to get DB records” would be of little help. Avoid such comments. Try to use comments for the following points:
At the beginning of the method, if the method name is not so much obvious. For example, AuthenticateUser is self explanatory. Don’t comment unless you have a complicated logic inside the module (instead of a straight forward entry check in database)
If a part of a module includes some complicated algorithms, then comment about it.
If a part of a code has constrains, explicitly mention it either in documentation or in comment. Mentioning it in comment would be of help if the user of module has access to source code and if he doesn’t bypass the comment without looking it by mistake.
If the language you are using for coding is “left to right”, make comments left align. It will increase readability.
Do not mix code and the comments; try to give blank lines between code lines and comment lines.
Documentation Blues:
Documentation has always been a nightmare for a programmer. A programmer always feels that he can skip the documentation part and instead serve the mankind by squeezing some more features into his product. But at the end of the day he still has to do the documentation. However, there are tools available in the market which can produce documentation on the basis of comments. JavaDoc (for Java) and Doxygen (for C, C++) are such two utilities which parse through the comments provided in the code and produce formatted documents for the code.
The CVS way:
There are some other tools available in market used for managing the changes done in source code known as version control software. Normally a programmer would open a file make his changes and save the file. In doing so, if some code has been deleted it would be lost. But while using these software the programmer saves the file into a virtual file-system instead of the file-system of the OS. The process of saving the file into this virtual file-system is known as check-in. The “Concurrent Versioning System” - CVS is one such software. CVS keeps a copy of each file which has been checked-in. So if one needs find out the change done in a file at any point of time he can do so by comparing the file with its previous version.
CVS also needs to keep comments about the file you check in. Since the comments are maintained at file level, so the comments keeps on adding to the last check-in information at the bottom of file. This information includes name of the person who checked in file, comments given by user when he checked in the file, and also the date and time of check-in. In this way CVS takes care of commenting the changes done in the file. You may add comment for “user authentication code added” while checking in the file into CVS server. If at some later stage some bug is found in the code then the new code can be found by comparing checked in file with older versions and the comments would tell why this new code was added. This way CVS give more managed way to comment at the file level for a give check-in.
XML is everywhere:
Yes it is. New languages started adopting everything as XML. All configurations, all settings, and now even all comments. That’s true. VS.NET IDE support XML commenting. Some predefined tags tell editor what type of comment it is. For example comment tags can be <code>, <example>, <param>, <summary>
There are three good reasons for using XML comments:
- Comments are now categorized. Now user of the file can have different level of abstraction. For example I may be only interested in summary of your code.
- Syntax check for comments. Compilers can do syntax check at compile time. For example, if not so then you can make a mistake of telling userName is for accepting user name as input where there is no such parameter to the function. Compiler can check such problems at compile time.
- XML comments are used for generating code documentations.
On the other Hand:
More the code visible on the screen, lesser the probability you will make a mistake. Consider for example you are writing a while loop which is 4 screen pages long. This way while coding you would probably need to move up and down couple of screens to view what you were writing or what was the variable you initialized at the beginning of the loop. Considering this, inline comments may consume considerable amount of area making a function stretch couple of screen pages more.
This point I am stressing here that commenting is an art. Comments should be precise and to the point. No-one expects you to write comments of philosophical or poetic significance. Please do-not write an essay where a line would have sufficed.
The Open Source Group:
In many open source and free software you will find some funny comments. For example, you may find the comment “you are not supposed to understand it”. I won’t go against it. This is done for fun, free open source software are coded for fun. No commercial thoughts are involved in it. Some teachers crack jokes in the class to make their lectures interesting. But thoughts expressed here are all about commercial software. If something is consuming resource then you must have a valid reason for it. I am not against these kinds of comments but while working in a professional environment one must refrain himself from putting such comments. However, while doing some free-lance coding you can always put some comments to spice things up.