Scilab Documentation Convention

Why should I use code documentation ?

Scilab is an open source project. As a result, many people are working on it and there are always some people entering the project and some leaving. Specially if you don't have any experienced Scilab developper to help you, it might be very difficult to understand the poorly documented code. The time spent documenting is, without any doubt, much lower than the one needed by the next person who will read the code.

Like in any professional project, we recommend to document the code. However, even if a software is used to generate online documentation, some rules are needed to achieve a consistent result, easier to understand. So we present a list of basic rules each developpers is asked to follow.

General Rules

The aim of automatic documentation is to get an easier understanding on how to use somebody else code without actually reading it. The description of functions, structures and other data should be clear enough. Nobody should need to enter the code to use them. The major point of documentation is to write for other people, not for yourself. When writting always consider that someone else will read your comments.

Here is a set of rules to keep in mind:

Describing Data

Describing files

Describing functions

Describing structures

Describing others data

Comment all define, typedef, enum, union,... Everything might not be as obvious as you can think. For enum, it may be interesting to comment each constant.

public: Rules for documentation (last edited 2011-03-30 16:18:40 by localhost)