Hi all,

I think there are two main problems regarding documentation:
- people tend not to write it (Atul’s comment)
- people tend not to read it

I have to admit I count amongst these people and I think I’m not alone ;-). Nevertheless I have started to realize the power of documentation and I’m trying to change…

Anders is totally right that reading the code gives a microscopic view of the solution and not the problem that is being solved. My first attempt to overcome this problem was

http://doc.calitko.org/architecture_overview.html

Have some of you guys read it (it’s not too big actually)? The architecture overview was supposed to give a macro view of Calitko. Did it succeed to do so? I have asked for comments before, but now I ask again as I think any such comments would be useful for this discussion.

I like Bo’s suggestion to “formalize” the structure of documentation. In my opinion writing good documentation is very similar to writing good unit tests. Both force you to think about the problem and the solution but from different perspectives. I was able to find bugs in my code when I was writing documentation, for example. To write something down I need to rethink the whole concept if I want write it down in a clear way. I admit keeping the docs consistent requires more work but maybe doxygen can assist us somehow (e.g. check whether the name after \a is actually a local variable and add support for StartUML if we decide to use it).

Regards,

Peter

Bob wrote: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.
*/