[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Coding standard for documentation?
From: |
John W. Eaton |
Subject: |
Re: Coding standard for documentation? |
Date: |
Wed, 30 Dec 2015 10:15:42 -0500 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Icedove/31.7.0 |
On 12/29/2015 08:58 PM, LachlanA wrote:
Greetings all,
The coding standards for Octave are very specific about where to put
whitespace and such, but seem to overlook inline documentation.
Would it be possible to have a standard such that all new functions and
classes have at least a couple of lines at the top explaining why they exist
and how they should be used (such as assumptions about the arguments, who is
responsible for deleting any dynamically allocated objects etc.)? The same
could apply for multi-line macros, which are used heavily in some files.
I think the reason we don't mention this in the Octave coding standards
is that the GNU coding standards already cover this topic. But I admit
that we haven't been good about following the guidelines.
See the fourth paragraph in this section:
http://www.gnu.org/prep/standards/standards.html#Comments
Some things I would modify about that section are that we should
probably be using markup that works with Doxygen since we are trying to
improve the quality of the online display of the sources.
I almost always prefer blocks of comments written in (nearly) complete
sentences with capitalization and punctuation over end-of-line comments,
even when they are just a single line.
And I truly despise comments of the form
// Return to calling function.
return;
or
// Iterate over the elements of FOO.
for (int i = 0; i < foo.length (); i++)
...
as they add absolutely no value.
Also, please don't add comments on the preprocessor conditionals. We
don't comment the end of IF/ELSE blocks in C++ and I don't see the point
of doing it for preprocessor conditionals either.
jwe