Hi Sebastien,

I think all agree that comments are very important and that’s the reason why all new code is required to have documentation. I would suggest that all code that is being refactored also be documented and tested before committed. This way gradually the complete code should be well documented.

The more difficult question is what and how much documentation is enough? I agree with Bo’s suggestion to formalize the documentation procedure I would extend it by saying that writing the documentation should be part of the creational process just as unit tests are part of it according to TDD. I think good documentation not only helps new developers understand what’s going one but also helps the developer writing the code better understand what the exact problem is and why he/she solves the problem exactly that way. Unit tests are part of the problem, so I think they should be documented as well. I’d expect that a sentence or two would be more than enough for most of the cases. If the documentation gets too big then maybe the class/function/test is too big and must be refactored.

Doxygen can generate some diagrams automatically although I don’t really find them useful most of the time. Doxygen can be modified to generate the output we desire, the problem is to figure out how to diagrams and document them accordingly. What about the architecture documentation? It’s generated by Doxygen from the comments of the namespaces and embedded dot diagrams. Supporting a tool that creates nicer UML diagrams will help a lot!

I guess Doxygen could (or be extended to) check whether everything is documented but it could easily be tricked by pasting an empty template. I think better and more productive would be to do pair-programming. We can’t do it in the real sense (sitting next to each other) but we can have at least two people work together on a single task. That’s the whole point about posting patches in Source Talk and discussing them. I just wished more people looked into the code and commented on it. I believe that this way of working will not only improve the quality of Calitko code but also help us improve ourselves.

Regards,

Peter

sebastien venot wrote:Hi

Yes comments is more than needed it is mandatory. There is otherwise no way for a new developer to join a project, or it would requires a lot of time to get into the coding.

A good way to force writing comments is to configure IDE like Eclipse to generate errors if methods does not have a proper comment on the top of it. I know it is possible in Java with JavaDoc tags, should be possible in C++ as well?

and as a rule a thumb, more comments is always better than not enough, and never think like: why comment? what i wrote is obvious.
Graphical documentation like UML would help even more or some diagram to show the actual exchange of packets in Gnutella (using Calitko object involved) …

regards

sebastien