Hi all,

In my point of view the comments in code is good for people (author and other readers) to understand the code. I agree with atul we don’t need to write long long comments, we only need to point out what is the most important.
I think the description of use cases and rationale suggested by Peter is very good. In case of need we can also explain the parameters, if the meaning or the usage of the parameter is not so clear.

Some other aspect can also be written in the comments, such as, the memory should be freed in this function or some special algorithms.

Regards,

Bob

atul wrote:

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.
*/