SV: SV: SV: Regarding coding style

[K Viltersten]

>>> 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.
> /**
> * Get the width of a box
> *
> * @param box   the box
> * @returns     its width
> */
> extern int box_get_width(box box);

Oh, yes. This is stupid. I agree with you.
If one's supposed to comment, let him 
comment RIGHT. Otherwise, let it be. 
Usually, when i comment my code, it's a
blessing. If not, i don't comment at all.

> 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.

I agree. Sometimes, there's a demand from 
the customer to comment all methods. Then, 
and then only, i'll go commenting all. But
i believe strongly that we think alike on
this one. When it's suitable, it should be
there. Otherwise - why bother. Right?

> 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.

I couldn't agree with you more on this one!
Thank you for an interesting discussion.

--
Regards
Konrad Viltersten
--------------------------------
sleep    - a substitute for coffee for the poor
ambition - lack of sense to be lazy