Re: commenting source code

josh wrote:
:: On 3 Gen, 19:15, "Bo Persson" <b...@gmb.dk> wrote:
::: red floyd wrote:
:::::
::::: Consider:
:::::
::::: * @param velocity in miles per second
::::: * @param seconds to range from 0 to 32 seconds.
:::::
::::: How do you convey that information in just the parameter name?
:::
::: Well, velocity is of course always in meters per second
::: (http://en.wikipedia.org/wiki/SI#Units:-), and if a parameter has
::: some kind of range of allowed values, it shouldn't just be called
::: seconds (or 's' for that matter). What does it really stand for??
:::
::: The real point is that end-user documentation should really
::: (please!) be written by a professional technical writer, not by
::: the programmer in the source code.
:::
::: Bo Persson
::
:: really do you think that every methods can be self-explanatory?

No, but I believe a lot of code could benefit from the programmer
trying to make it so.

:: I don't think so. I think that if Java API's creators and .NET
:: API's creators have
:: created a way (Javadoc for Java and XML tag sintax for .NET) for
:: documenting code, may
:: be, they have had some good reasons. I think it's important have
:: for developers a standard way to write comments to their code so
:: others can create tool to extract that informations to produce,
:: automatically, technical documentation

It is a poor man's excuse for documentation, IMO. :-)

:: and than who is better that
:: the programmer to document their code?

I told you above, a professional technical writer. One who specializes
in writing, not programming.

I once worked for a large company producing PCs (no less), where a
development department consisted of three separate groups of people -
hardware, software, and documentation. To have the programmers (or
hardware engineers!) write anything for end-users were just
unthinkable!

Bo Persson