C++ code documentation/annotation

M

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?
 
V

Victor Bazarov

Matthias said:
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
 
M

Matthias Kaeppler

Victor said:
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.



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.



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

Victor Bazarov

Matthias said:
[..]
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
 
J

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

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
 
J

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

Matthias Kaeppler

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

Fabio Fracassi

Matthias said:
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
 
P

Pete Becker

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

Yuriy Solodkyy

Hi,

I think sticking to doxygen style annotation wouldn't be a bad idea as
it is mostly derived from Java-doc syntax and is hence more or less de
facto standard in the field. And you don't have to do much to start
with: just have all the comments related to different things in your
program started from /// instead of // and doxygen will pick them up.

Actually it doesn't really matter which convention you choose: as long
as you are consistent you'll be able to convert one to another with a
small script. For some course we had to work with API written in UIUC
that had a lot of very good and well-structured comments, but they were
not in doxygen style. With some 20-lines script we managed to convert
source so that doxygen could pick up almost everything. Here is what
we've got: http://parasol.tamu.edu/~yuriys/polaris/ and here is what we
had before just by running doxygen on unmodified files:
http://parasol.tamu.edu/people/rwerger/MiniPolaris_html/docs/index.html
Compare for example Expression and List<> classes in both
documentations. To see what was changed in code in order to support all
that, see the source code in both documentations.

If you work under Windows, have a look also at .chm file which you can
download from the first page. Doxygen generates it too and the nice
thing about it is that you can embed it into your MSDN installation so
that when you press F1 on something related to your code, Visual Studio
will find it in the documentation in the same way it finds Win32 API
functions.

We've been using doxygen for quite some time already for generating both
internal and user documentation and are very happy about it. Couple of
my friends managed to convince their companies to start using doxygen
after they saw some good examples of what it can do. Give it a try! And
don't treat this post as an advertisement, I just really find this tool
very useful ;-)

Yuriy
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,744
Messages
2,569,484
Members
44,903
Latest member
orderPeak8CBDGummies

Latest Threads

Top