Monday, May 07, 2007

Commenting your code

Comments are an integral part of any program, even though they do not contribute to the logic. Appropriate comments add to the maintainability of a software. I have heard developers complain about not remembering the logic of some code they wrote a few months back. Can you imagine how difficult it can be to understand programs written by others, when we sometimes find it hard to understand our own code. It is a nightmare to maintain programs that are not appropriately commented. Java classes should contain comments at various levels.
There are two types of comments; implementation comments and documentation comments. Implementation comments usually explain design desicisions, or a particularly intricate peice of code. If you find the need to make a lot of implementation comments, then it may signal overly complex code. Documentation comments usually describe the API of a program, they are meant for developers who are going to use your classes.
All classes, methods and variables should have comments inserted in the source code at appropriate places. Comments should follow Javadoc standards so that we can generate separate API documentation from the source files without extra effort. Remember that commenting appropriately means neither over-commenting nor under-commenting.






The screencast shown below explains how I had commented a Java program I wrote several years back. The animation will automatically start buffering. Click on the square on the right hand side in the controls to display the movie, and then the play button to start the movie.













Discuss this post in the learning forum.



Note: This text was originally posted on my earlier blog at http://www.adaptivelearningonline.net


 


 



Commercial Links


No comments: