Hi Bob

This is indeed one of the most discussed topics in the histpry of programming … ;-)

In “Practice of programming” ( Kernighan & Pike ), best comments briefly point out salient details ( or a large scale view ). I remember reading Rob Pike recommending against long comments…

Rather, if the function/method is short ( and expressed clearly/idiomatically ) then usually a one line comment suffices.

I think there are a few problems with the template you suggested. The biggest is keeping comment in sync with code … which usually does not happen ( IFAIK ).
Let me know what you and others think

– cheers atul

Bob wrote:

Hi everyone,

These days I am reading the source code of Calitko, I found there are very little comments in the source code, especially for the methods of classes. As Calitko is getting bigger and bigger, the code will become harder and harder to understand.
I would be better that we write some comments for methods and also for members of classes. It would be easier to let the new comers to understand the source code and the authors will not forget the original purposes of the class.
I would like to suggest, we use a templet for all the functions.

What do you think?:)

Bo

/*
* Parameters:
* packet:
*
* Return:
* void
*
* Purpose:
* Notify the other classes, who are interested in the packets.
*
* Scenario:
* One example of the calling procedure.
*/