Commenting codes
Uh.. head hurts.. must bang head to sidewalk
I don’t know much about software quality but I’ve been reading some codes that I’m supposed to continue and came up with these guideline.
1. Document eveything. This is a cliche. It really helps the person who’s going to use your classes. Prepare a design document before hand and please use natural language when doing that. Think of it as telling a sci fi story to your 60 year old parents. Surely, you won’t include such technical details when doing that, right?
2. Please use meaningful comments. A neat trick that i’ve been using is copy and paste the stuff i’ve written in my design docs and code according to them.
3. Only sentence case or title case when commenting. A PARAGRAPH WITH ALL THE LETTERS IN UPPERCASE MAKES IT REALLY HARD TO FOCUS ON THE MORE IMPORTANT STUFF WHICH ARE THE CODES.
3. Limit the symbols. Borders are good. But like drugs, too much is bad. For example, instead of this
//————————————————
//DrawLabel
//
//Draw text.
//Draws within the rectangle area specified by rRect.
//————————————————
Why not this?
//Name: DrawLabel
//Purpose: Draws Text
//Description : Draws within the rectangle area
//specified by rRect.
This would be better, don’t you think? Its clean and fits the objective.
4. Peer review the comments. Yes, I know that it’s boring and takes too much time but remember, the purpose of comments is to help future developer. If your peer who knew you can’t understand your comments, what makes you think a stranger can?
Good night.
