Re: Coding standard for documentation?

[John W. Eaton]

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