SV: SV: Regarding coding style

[Ben C]

On 2008-03-08, K Viltersten <tmp1 at viltersten.com> wrote:
>> If you can't/don't look at the source file, 
>> then comments aren't going to help (except 
>> in the case of something like docstrings in 
>> Python).
>
> I strongly disagree. Now, perhaps we're 
> talking about different things, here?
> Usually, in the header file (C++), there
> won't be any source code, except for 
> method declarations. A common example:
>
> /** Projects an object from 3D to 2D using
>     the method of Alexander The Great.
>     \param 3D structure to be projected
>     \returns 2D projection
> */
> public Proj2D get2Dfrom3D(Proj3D param);
>
> The above is, to me, very clear and 
> consistent. Not to mention, easily 
> handled with e.g. Doxygen to create a
> readable documentation.
>
> I don't see how this is dislikeable. Please 
> explain. Perhaps the above IS what you 
> ment by "docstrings"? For Java, one has the
> JavaDocs, a great tool, provided one will
> comment each method and variable used.

The problem is that tools like Doxygen and JavaDocs generate warnings
and errors and things if everything isn't documented "completely". So
you end up with a lot of silly boilerplate.

I see this kind of nonsense a lot:

/**
 * Get the width of a box
 *
 * @param box   the box
 * @returns     its width
 */
extern int box_get_width(box box);

You are right that is it often useful to document what to pass to a
method and what to expect back and that if this is done well in many
cases it isn't necessary to see the implementation.

But in many other cases it's obvious, and in other cases it's obvious if
you just look at the source which you've got.

What's needed is just a bit of common sense and pragmatism: APIs need
more documentation if the source of the implementation isn't being
released with them, and some APIs just need more documentation than
others anyway.

Python docstrings, like most things in Python, demonstrate this kind of
common sense: you write what you want in them and as far as I can tell
nothing complains if you don't write them at all.

The lack of fascism is the big innovation. It sounds simple but it makes
a huge difference: it's much easier to find (and keep up to date) the
real documentation if it's not hidden in a forest of bogus
documentation.