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 I only rarely went back to document code that was “finished” to some extent. That has changed though and all new code that is published for submission must be documented and unit tested.

Currently only the doxygen syntax is presented in the Coding Conventions but after the discussion here I’ll add a section on what information should be provided when documenting the code. I was kind of thinking in the same direction recently but only regarding description of classes. You are right though that functions need to be documented better too.

I agree with you about the “Purpose” section of the documentation. I’m thinking about “Rationale” as more appropriate word though (what do others think?). In my opinion the rationale should describe the problem, which the class is trying to solve, without saying anything about the solution!

As a separate part some use-cases could be presented. That is similar to your scenario, however use-cases should be more abstract – maybe just informal description of possible uses of the class.

A further part would be the unit tests which will have to cover the use cases completely (and these are some real “scenarios” with working code as example). If we follow test driven development, unit tests should be the first thing we write (after the rationale and the use-cases) before starting the implementation. Unit tests would help us figure out a better interface because we will not be thinking of the details of the implementation.

I just listened to an interview with Ron Jeffries, who said he is not writing all the test all at once, rather writing a test, then the code to make the test run through, then again a test, then again code an so on in a purely incremental manner. Here is the link to a number of quite interesting interviews taken by Bruce Eckel:

http://www.mindviewinc.com/mediacast/interviews/Index.php

Now back to the topic, there could be an additional section of the documentation describing the chosen implementation. In this way we would have an outside and inside view of the class in both informal (text) and formal (code) form.

I think explicitly giving documenting the parameters and the return value may not always be necessary as it will result in unnecessary duplication (return type for example is both in the documentation and the function prototype). I guess the informal textual description of the rationale behind the function and the informal (textual) description of the solution should be enough.

That’s quite an interesting topic and it would be great if we have more people taking part in the discussion!

Regards,

Peter

P.S. We can extend doxygen by some new keywords like \rationale, \usecase and \realization for example and do some special formatting for the sections.

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