Re: commenting source code

From:

"Bo Persson" <bop@gmb.dk>

Newsgroups:

comp.lang.c++

Date:

Thu, 3 Jan 2008 19:15:58 +0100

Message-ID:

<5u4n2uF1fu6slU1@mid.individual.net>

red floyd wrote:
:: Bo Persson wrote:
::: josh wrote:
::::: On 3 Gen, 09:12, Kira Yamato <kira...@earthlink.net> wrote:
:::::: On 2008-01-02 10:44:02 -0500, josh <xdevel1...@gmail.com> said:
::::::
::::::: Hi,
::::::
::::::: I wish to write comments to my source code using a technology
::::::: like JavaDoc.
::::::
:::::: Comments? Pshh... If you need to comment your code, then
:::::: you're not writing good code. Good code will always
:::::: "self-document" itself.
::::::
:::::: *runs and ducks for cover from incoming flames*
::::::
:::::: --
::::::
:::::: -kira
:::::
::::: yes ... but, in my opinion, it's important to comment methods
::::: saying what they do, their params and so on....
::::: if you look at some professional code source (pick them from
::::: sourceforge) you'll see some comments......
:::
::: The point right here is rather that you could *name* the
::: functions, saying what they do.
:::
::: Instead of writing this:
:::
::: * @param h hour
::: * @param m minute
:::
::: explaining that h means hour and m means minute, why not just
::: call the parameters hour and minute?
:::
::
:: Because often you need to document constraints, units, etc... for
:: the *users* of your code. IMHO Doxygen/Javadoc/etc are to provide
:: interface documentation for the end-user, not to provide internal
:: documentation.
::
:: The example was perhaps not the best.

No, and I wasn't fully serious either, but we often see this way of
writing lots of comments about what could already have been in the
code.

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