Re: Documenting Octave Source

[John W. Eaton]

On 27-Feb-2004, JD Cole <address@hidden> wrote:

|     This, of course, is a very easy plan to implement, it just needs the 
| blessing of "he who holds the keys to the  city [cvs]". Hint, hint....
| 
|     I think to reduce the amount of work that jwe would have to do in 
| order to integrate comments such as these, it should be the 
| responsibility of the of contributor to ONLY give diffs for the comments 
| and make sure that it is with respect to the CURRENT cvs.

I think the reason that Octave's source code doesn't have a lot of
comments is because the typical function is small and has a fairly
clear purpose.  This is not always true, and I often find that if I am
unable to understand what a function is doing by just reading the
code, it usually turns out that there is a simpler way to write the
code that makes it easy to understand.  I also find that trying to
write comments (or documentation) for a badly designed function tends
to make it clearer that the code is badly written.

In any case, I have no objection to patches that add comments provided
that

  * The comments are actually useful.  Meta-comments about the intent
    of a code block or the purpose of data members in a class are much
    more likely to be useful than comments on each line of code.

  * Match the formatting of the comments in the rest of Octave.  For
    example, please try to follow the guidelines of the GNU coding
    standards, but use C++ style comments.  Write about arguments by
    using their parameter names in all caps.

  * Use mostly complete sentences and puntuation.

  * Send patches with one patch per message with one set of comments
    about a single topic or bit of code.  It is too difficult to sort
    through a large patch and decide what to keep.  I'm already a
    major bottleneck in the process of getting patches into Octave, so
    any help you can provide to make the process easier is
    appreciated.

Thanks,

jwe