commenting source code

[josh]

Hi,

I wish to write comments to my source code using a technology like
JavaDoc.

any idea?

P.S.
under Linux I remember that there is something...but I don't remember
the tool name!

Thanks

 

[AnonMail2005]

Hi,

I wish to write comments to my source code using a technology like
JavaDoc.

any idea?

P.S.
under Linux I remember that there is something...but I don't remember
the tool name!

Thanks

I'm not familiar with JavaDoc but you can extract code comments
that are suitably tagged using Doxygen. It also does many other
documentation related things such as class diagrams.

HTH

 

[Puppet_Sock]

I wish to write comments to my source code using a technology like
JavaDoc.

any idea?

I'm wondering why?

I can see using automated tools to create documentation
outside the code. But I don't quite get the point of
using automated tools to produce comments in the code.
With the exception of *some* code creation wizards,
where they create comments like "insert event handler
here" or the like. Those can be useful *sometimes*.
Socks

 

[James Kanze]

[snip]

I wish to write comments to my source code using a technology like
JavaDoc.
any idea?

I'm wondering why?

Because it's there.

I can see using automated tools to create documentation
outside the code. But I don't quite get the point of
using automated tools to produce comments in the code.
With the exception of *some* code creation wizards,
where they create comments like "insert event handler
here" or the like. Those can be useful *sometimes*.

His reference makes me think that he's looking for something
like JavaDoc, which extracts comments from the source code to
generate nice looking documentation. For that, C++ has Doxygen,
which is a lot more flexible than JavaDoc, but can be used
similarly if you really want to limit yourself. (For example,
Doxygen allows grouping of similar functions, with a common
documentation for all of them. When I last used it, JavaDoc
didn't.)

As for my comment: "Why? Because it's there", a more accurate
response would be "Because nothing else is there." Both JavaDoc
and Doxygen approach things backwards: what you want is a tool
which generates the C++ header from the class specification
and/or the class diagrams. There are some tools which do a
partial job: Rational Rose, for example, can generate the
headers (and the framework of the source file) from class
diagrams, but it is fairly awkward to add comments for things
like pre and post-conditions. And CWeb will generate both the
header file (and source file, if you want) and really beautiful
printed documentation from a CWeb source, which is basically
LaTeX which some added commands. Thus, with very poor support
for diagrams, and a fairly complicated format and command
language for the files you actually edit.

In sum, none of the available solutions is perfect. My own
choice would be to use Rational Rose, but I'd like to get a bit
more experience with CWeb as well. Now if someone would only
come up with a system that combined the best of both. At a
reasonable price, so that students and hobby programmers could
use it as well.

 

[josh]

I'm wondering why?

simply for extracting documentation for my code:

for example when I write a method I wish to use a syntax like that
(javadoc) or similar (Doxygen):

/**
* set datetime and then....
*
* @param h hour
* @param m minute
* @param s seconds
* @return an <code> integer </code> that....
*/

than I use a tool that parse my source code and read that comments
and produce a well-formatted source code documentation exporting it
in HTML, Latex ecc.

Regards

 

[Kira Yamato]

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*

 

[josh]

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*

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


Javadoc, Doxygen et cetera are for that purpose and in fact that's
also my goal!

 

[Bo Persson]

josh wrote:
::: On 2008-01-02 10:44:02 -0500, josh <[email protected]> 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?

Saves you a lot of writing!

:: Javadoc, Doxygen et cetera are for that purpose and in fact that's
:: also my goal!

Ok.

Bo Persson

 

[red floyd]

josh wrote:
::: On 2008-01-02 10:44:02 -0500, josh <[email protected]> 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.

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?

 

[Bo Persson]

red floyd wrote:
:: Bo Persson wrote:
::: josh wrote:
:::::: On 2008-01-02 10:44:02 -0500, josh <[email protected]> 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

 

[Puppet_Sock]

than I use a tool that parse my source code and read that comments
and produce a well-formatted source code documentation exporting it
in HTML, Latex ecc.

Oh. The other way around. You said write *comments*
*to* your source code. You meant write *docuemnts*
*about* your source code.

I understood you to mean you wanted a tool that
would automatically write comments into your
source code. That still seems fairly low calorie.
Socks

 

[Ian Collins]

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.

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?

typedef int MilesPerSecond;

void f( MilesPerSecond velocity, unsigned seconds )
{
assert( seconds < 33 );

....

 

[James Kanze]

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?

double accellerationInMilesPerSecondPerSecond(
double velocityInMilesPerSecond,
double secondsWithPreconditionGE0AndLE32 ) ;

?

Note that we're still dealing with a very simple example. Real
functions have a great deal more pre- and post-conditions, and
often have documented error responses, so you'd end up with
something like:

void
writeToFileThrowingWriteErrorExceptionInCaseOfWriteErrorAnd...

The whole idea is really a bit ridiculous.

 

[josh]

red floyd wrote:
:: Bo Persson wrote:
::: josh wrote:

:::::: On 2008-01-02 10:44:02 -0500, josh <[email protected]> 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

really do you think that every methods can be self-explanatory?
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 and than who is better that the
programmer to document their code? Furthermore I think it's important
to have for programmers standard ways to "communicate". I can give you
another example. What about style formatting code? It's another way to
make code source more readable for the same programmer and for
others.......

Regards

 

[Bo Persson]

josh 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

 

[Ian Collins]

Bo Persson wrote:

[you appear to have a non-standard quote character, which is distracting]

josh wrote:

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

The target audience for code documentation tends to be fellow
programmers, not end users. I've yet to find a technical writer who
understands C++ well enough to document it.

I prefer to document through unit tests, but that's another thread!

 

[Grizlyk]

Hi everybody.

If you need to comment your code, then you're not
writing good code.  Good code will always
"self-document" itself.

This is wrogn idea (about self-documented code). There are some
reasons for comments:

1. There are no ideal programming languages, so any of them is more
restricted than a human language, so we can not elide comments.

2. Any real programming language has namy weak points in the sense of
self-commenting, for example:
char* get_buf();
Do we need call delete or delete[] for returned "char*"?
Else
auto char* get_buf();
or
heap[] char* get_buf();
can be more self-documented and any usage of delete or delete[] can be
controlled by compiler .

3. But there is more important thing, that C++ source code often used
during desing stage (in comparison with coding stage) and C++ has no
other standard form of representation of itself for design stage.

One can guess, that there are some information, strictly required for
desing, but the information never will be used for coding. Due to the
"no need for coding" the desing information never will be part of
programming language without or with weak support of desing stage.

That is why, comments keep the design information, but without any
support of the commented requirements from the side of a desing tool.

But if C++ will in future have great support of desing stage, the
formal nature of programming language will force us to use comments
also.

By the way. I sometimes think about the thing - how could we include
the support of the desing stage in C++? - but are still without
valueable, detectable success.

In accordance with ideas of spring of the last year, for object-
oriented paradigm, source of C++ must be able to be represented from
plain file into as "class items" (parts of class's interface, such as
"messages" and its implementing "methods") and back, from "class
items" into compilation unit - ordinary C++ file.

The "class items" could be displayed as "pure" object-oriented desing
tool, with ability to work with interfaces (stryctly dividing
interface and implementation) and simultaneosly with one to fast
switch into implementation of any method.

Any hints?

 

[Kira Yamato]

Hi everybody.



This is wrogn idea (about self-documented code).

Dude, are you aware of an literary device called hyperbole --- "an
exaggerated statement used for effect and not meant to be taken
literally"?

Another example, "The best code is no code at all."

The point here is that you should always choose a coding style that
allows the code to speak as much as possible about what its own
intentions are. It often leads to more robust code also, not just more
readable code.

[...]

 

[Grizlyk]

Dude, are you aware of an literary device called hyperbole --- "an
exaggerated statement used for effect and not meant to be taken
literally"?

Another example, "The best code is nocode at all."

Dude? The word is unknonwn for me, but from first time looks (related
to my language) rather like curses .

Well, dude, i agree, that "you should always choose a coding style
that allows the code to speak as much as possible", this is quite self-
evidently.

But it seems to me, that the kind of "device called hyperbole" can not
be applyed here, just because comments are required and never can be
elided (this is exactly i have tryed to write about). Never.

For "device called hyperbole" it would be "there is no nocode (read
best code) without comments".

Returning to OP i do not know a good stuff for commenting. If the
stuff will used outside of compilation or desing scope, then any stuff
can be used - all of them poor.