C++ code documentation/annotation

[Matthias Kaeppler]

Hello,

I was wondering if there are any guidelines or established ways or
styles or even scripts or programs to annotate and document C++ code,
especially method headers and classes.

I'm not necessarily asking for something like doxygen, which generates
an API HTML doc from your code. This only makes sense for public APIs
IMHO. But generating uniform class and method annotations by using C++
comments would be a nice thing.

In case there is no such thing, and I should have to write the
annotations myself using C++ comments, what layout to do that is
commonly used and preferred? Is there some sort of style guide like e.g.
for Java annotations?

--
Matthias Kaeppler

[Victor Bazarov]

Matthias Kaeppler wrote:

I was wondering if there are any guidelines or established ways or
styles or even scripts or programs to annotate and document C++ code,
especially method headers and classes.
Yes, there are guidelines. Scripts or programs do not really make much
sense since they can't figure out the intent, and whatever they can come
up with, is already in the code. I don't believe an annotation like

a++; // increment 'a'

is of any value, but that's all an automated annotator can do.
I'm not necessarily asking for something like doxygen, which generates
an API HTML doc from your code. This only makes sense for public APIs
IMHO. But generating uniform class and method annotations by using C++
comments would be a nice thing.
And usually it is. Those things are usually defined in what is commonly
known as "coding style documents". Development groups usually publish
something like that for internal consumption.
In case there is no such thing, and I should have to write the
annotations myself using C++ comments, what layout to do that is
commonly used and preferred? Is there some sort of style guide like e.g.
for Java annotations?

I don't believe there is a commonly accepted way. It's like naming of
class members or functions -- people do what they think is right and what
they think makes code more readable, and those things are as individual
as people who think those up.

V

[Matthias Kaeppler]

Victor Bazarov wrote:

Matthias Kaeppler wrote:

I was wondering if there are any guidelines or established ways or
styles or even scripts or programs to annotate and document C++ code,
especially method headers and classes.

Yes, there are guidelines. Scripts or programs do not really make much
sense since they can't figure out the intent, and whatever they can come
up with, is already in the code. I don't believe an annotation like

a++; // increment 'a'

is of any value, but that's all an automated annotator can do.

I'm not necessarily asking for something like doxygen, which generates
an API HTML doc from your code. This only makes sense for public APIs
IMHO. But generating uniform class and method annotations by using C++
comments would be a nice thing.

And usually it is. Those things are usually defined in what is commonly
known as "coding style documents". Development groups usually publish
something like that for internal consumption.

In case there is no such thing, and I should have to write the
annotations myself using C++ comments, what layout to do that is
commonly used and preferred? Is there some sort of style guide like
e.g. for Java annotations?

I don't believe there is a commonly accepted way. It's like naming of
class members or functions -- people do what they think is right and what
they think makes code more readable, and those things are as individual
as people who think those up.

V

How do you comment your method definitions?
Back when I used Visual Studio, I had a macro generating a
comment-template from method headers, which looked roughly like this:

// METHOD NAME: Bar::foo
// RETURN TYPE: void
// DESCRIPTION: Foos a bar.
void Bar::foo()
{
//...
}

Of course the description had to be filled in manually, but the rest was
created by a VB macro automatically when the macro was invoked on the
selected function header.

However I use Emacs now and I haven't found the time to learn Lisp yet,
so I don't use any macros right now.

--
Matthias Kaeppler

[Victor Bazarov]

Matthias Kaeppler wrote:

[..]
How do you comment your method definitions?
Sparsely.
Back when I used Visual Studio, I had a macro generating a
comment-template from method headers, which looked roughly like this:

// METHOD NAME: Bar::foo
// RETURN TYPE: void
// DESCRIPTION: Foos a bar.
void Bar::foo()
{
//...
}

Of course the description had to be filled in manually, but the rest was
created by a VB macro automatically when the macro was invoked on the
selected function header.

However I use Emacs now and I haven't found the time to learn Lisp yet,
so I don't use any macros right now.

Honestly, now, do you really need the first two parts of the "header
comment"? Is that really so hard to gather from the function declaration
that its name is 'Bar::foo' and that it returns 'void'?

I do comment my functions, but mostly if certain aspects of them are not
obvious from the name and/or argument types/names. Example

// saves the data object in a file
// if fname is 0, saves in a file using filename data member
// saves into a different file if filename is given
// if rename is true, stores the fname as the new filename.
//
int data::save(const char* fname /* = 0*/, bool rename /* = false */)
{
...

(No, I don't have a class named 'data', this is just for illustration)

Sometimes this comment is placed inside the function itself, before the
first statement, and I am not very consistent about that.

We don't use Doxygen yet, so we don't have nice headers above every
functions (although we probably should).

V

[jdog1016]

There are a few things that I find useful in comment blocks preceding
functions:

1) A short description of what it does. Maybe even precondition and
postcondition.

2) What functions call this function

As someone else said, development groups normally have their own
standards for things like this. For example, there are standards for
editing the linux kernel
(http://pantransit.reptiles.org/prog/CodingStyle.html)
and standards for editing FreeBSD code
(http://www.hmug.org/man/9/style.html).

[Pete Becker]

jd******@gmail.com wrote:

2) What functions call this function

Really? Seems like a lot of busywork to keep that up to date. I use grep
when I need that information.

--

Pete Becker
Dinkumware, Ltd. (http://www.dinkumware.com)

[Stephen Howe]

>....or even scripts or programs to annotate and document C++ code,

especially method headers and classes.

A script or program might tell you _what_ a chunk of code is doing.
It wont tell you _why_. Only a human can do that.
And comments on "why" are more important than "what". A commnet on "why"
allows a fellow programmer to judge whether the code does what the progammer
intended (or not).

Stephen Howe

[jdog1016]

> Really? Seems like a lot of busywork to keep that up to

date. I use grep
when I need that information.

I actually agree, and that's what I do too. But ideally, it certainly
would be nice to have that information right there :)

[Matthias Kaeppler]

jd******@gmail.com wrote:

There are a few things that I find useful in comment blocks preceding
functions:

1) A short description of what it does. Maybe even precondition and
postcondition.

2) What functions call this function

As someone else said, development groups normally have their own
standards for things like this. For example, there are standards for
editing the linux kernel
(http://pantransit.reptiles.org/prog/CodingStyle.html)
and standards for editing FreeBSD code
(http://www.hmug.org/man/9/style.html).

Interesting, especially the first one was a funny read :)

By the way (I'm probably beating dead horses here), what is the
rationale behind using opening curly braces in the same line? I know
Java has that in its style guide, too, but I could never figure out why
this should be useful, except maybe making the code more compact but
also harder to read.
That's also why I never do that. It might be okay for class and
namespace definitions, but for anything else, I think it's horrible.
After three indentations, you have no idea where a block starts or ends!

--
Matthias Kaeppler

[Fabio Fracassi]

Matthias Kaeppler wrote:

jd******@gmail.com wrote:

There are a few things that I find useful in comment blocks preceding
functions:

1) A short description of what it does. Maybe even precondition and
postcondition.

2) What functions call this function

As someone else said, development groups normally have their own
standards for things like this. For example, there are standards for
editing the linux kernel
(http://pantransit.reptiles.org/prog/CodingStyle.html)
and standards for editing FreeBSD code
(http://www.hmug.org/man/9/style.html).

Interesting, especially the first one was a funny read :)

By the way (I'm probably beating dead horses here), what is the
rationale behind using opening curly braces in the same line? I know
Java has that in its style guide, too, but I could never figure out why
this should be useful, except maybe making the code more compact but
also harder to read.

I think it is a matter of taste. I for one find

int someFunc(int parameter) {

int result = 2 * parameter;

return result;
}

much nicer than

int someFunc(int parameter)
{
int result = 2 * parameter;

return result;
}

Why do you find the later easier to read?
I think the former is much clearer. The first line with the same identation
is the beginning of a block.

When having many nested blocks which all end at the same time (which happens
very rarely, since such functions are usually split) you simply add an
occassional comment at the ending brace:

for (int x=0; x < 10; ++x) {
for (int y=0; y < 10; ++y) {
// some other code...
} // for x
} // for y
That's also why I never do that. It might be okay for class and
namespace definitions, but for anything else, I think it's horrible.
After three indentations, you have no idea where a block starts or ends!

I realy see no difference there. The block starts at the line which has the
same Identation as the ending brace, regardless of where you place the
opening brace.
I guess it has to do with what you account as the beginning of the block.
For me the statment before the opening brace opens the block.

I guess everybody uses what he likes best, or what the design guide of the
current Project asks her too.

Fabio

[Pete Becker]

jd******@gmail.com wrote:

I actually agree, and that's what I do too. But ideally, it certainly
would be nice to have that information right there :)

Well, maybe. Code browsers can do that if you need it. Any static
statement of who calls whom is redundant, though, and requires
additional maintenance, which is usually a bad thing.

--

Pete Becker
Dinkumware, Ltd. (http://www.dinkumware.com)