About comments in the source code

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

Would you like to post a relpy?


This post starts a thread.
Follow-ups:
Re: About comments in the source code
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 (more...)
Re: About comments in the source code
Hi all, I think also having some kind of design documentation using UML would be a good thing to get an overview of modules etc. StarUML seems to be a pretty (more...)
Re: About comments in the source code
Hi Bob, That’s a nice suggestion! Actually we already do something in this respect. It is true some parts of the code are not documented and the reason for that is (more...)