Documenting C Code

[Jeff Rodriguez]

What sort of documentation do you do on your code? I've never done any code
development on a big project and I want to start documenting my code in a way
that makes sense, is easy to understand, informative, etc.

How would you document:
*.c file headers
*.h file headers
Functions
Variables?

Jeff

Maybe a little OT, but I want a C specific viewpoint. Also, are there tools
similar to JavaDoc for C?

[Jack Klein]

On Mon, 17 Nov 2003 20:34:52 -0700, Jeff Rodriguez
<ne********@gurugeek.EXAMPLENOSPAM.com> wrote in comp.lang.c:

What sort of documentation do you do on your code? I've never done any code
development on a big project and I want to start documenting my code in a way
that makes sense, is easy to understand, informative, etc.

How would you document:
*.c file headers
*.h file headers
Functions
Variables?

Jeff

Maybe a little OT, but I want a C specific viewpoint. Also, are there tools
similar to JavaDoc for C?

www.doxygen.org

--
Jack Klein
Home: http://JK-Technology.Com
FAQs for
comp.lang.c http://www.eskimo.com/~scs/C-faq/top.html
comp.lang.c++ http://www.parashift.com/c++-faq-lite/
alt.comp.lang.learn.c-c++ ftp://snurse-l.org/pub/acllc-c++/faq

[Richard Heathfield]

Jeff Rodriguez wrote:

What sort of documentation do you do on your code? I've never done any
code development on a big project and I want to start documenting my code
in a way that makes sense, is easy to understand, informative, etc.

How would you document:
*.c file headers
*.h file headers
Functions
Variables?

Jeff

Maybe a little OT, but I want a C specific viewpoint. Also, are there
tools similar to JavaDoc for C?

Doxygen makes a great starting point for documenting C code, but it's not
the be all and end all. What you really need to document is not so much the
data types and functions themselves (although that is important, and
Doxygen can certainly help you with that) but the relationships between
them *and how to use those relationships*. This is key; this is critical;
and this is where most documentation fails.
--
Richard Heathfield : bi****@eton.powernet.co.uk
"Usenet is a strange place." - Dennis M Ritchie, 29 July 1999.
C FAQ: http://www.eskimo.com/~scs/C-faq/top.html
K&R answers, C books, etc: http://users.powernet.co.uk/eton

[Christian Bau]

In article <Zqgub.19692$Ro5.18776@fed1read07>,
Jeff Rodriguez <ne********@gurugeek.EXAMPLENOSPAM.com> wrote:

What sort of documentation do you do on your code? I've never done any code
development on a big project and I want to start documenting my code in a way
that makes sense, is easy to understand, informative, etc.

How would you document:
*.c file headers
*.h file headers
Functions
Variables?

Jeff

Maybe a little OT, but I want a C specific viewpoint. Also, are there tools
similar to JavaDoc for C?

For every extern function, write a comment describing what the function
does. The comment must be precise enough so that if you threw away the
source code of the function, I could rewrite it using the comments
alone. Then unless it is obvious, add a description why I would want to
call that function.

[John Bode]

Jeff Rodriguez <ne********@gurugeek.EXAMPLENOSPAM.com> wrote in message news:<Zqgub.19692$Ro5.18776@fed1read07>...

What sort of documentation do you do on your code? I've never done any code
development on a big project and I want to start documenting my code in a way
that makes sense, is easy to understand, informative, etc.

How would you document:
*.c file headers
*.h file headers
Functions
Variables?

Here are my general rules:

1. Don't document the obvious. We know how ++, --, and other
operators work.
2. Keep comments high-level, describing the general intent of
the code. Don't just re-express the algorithm in English; tell
us *why* you're doing something.

Right: For each name in the array, extract the surname.

Wrong: Set i to 0. Loop from 0 to 10. Call strchr() on a[i],
looking for the first ' ' character. Return the pointer
the character immediately following the ' '.

3. Use inline comments to refer to standards and practices,
explain non-obvious code, or to justify a hack.
4. Have a doc block at the head of each file describing the
purpose of that module, again keeping everything high-level.
5. Have a doc block for each function that lists the function name,
purpose (high-level), inputs, outputs, return values (and for C++
and Java, exceptions thrown).
6. Use descriptive and meaningful names for variables, constants,
and functions.
Jeff

Maybe a little OT, but I want a C specific viewpoint. Also, are there tools
similar to JavaDoc for C?

If there are, I've never seen one.

[Joona I Palaste]

John Bode <jo*******@my-deja.com> scribbled the following:

3. Use inline comments to refer to standards and practices,
explain non-obvious code, or to justify a hack.

Also, if you're working on a multiple-person project, you can write
inline comments like "Fred: Please add real implementation here" or
"Are you sure THIS is what you want to do? Left unchanged just in case."
In our company, we write comments like these every now and then.

--
/-- Joona Palaste (pa*****@cc.helsinki.fi) ------------- Finland --------\
\-- http://www.helsinki.fi/~palaste --------------------- rules! --------/
"How can we possibly use sex to get what we want? Sex IS what we want."
- Dr. Frasier Crane

[Mike Wahler]

"Joona I Palaste" <pa*****@cc.helsinki.fi> wrote in message
news:bp**********@oravannahka.helsinki.fi...

John Bode <jo*******@my-deja.com> scribbled the following:

3. Use inline comments to refer to standards and practices,
explain non-obvious code, or to justify a hack.

Also, if you're working on a multiple-person project, you can write
inline comments like "Fred: Please add real implementation here" or
"Are you sure THIS is what you want to do? Left unchanged just in case."
In our company, we write comments like these every now and then.

I've also worked at places where this was done, and sometimes
it escalated into arguments. Sort of like a newsgroup in the
code. :-)

-Mike

[Joona I Palaste]

Mike Wahler <mk******@mkwahler.net> scribbled the following:

"Joona I Palaste" <pa*****@cc.helsinki.fi> wrote in message
news:bp**********@oravannahka.helsinki.fi...

John Bode <jo*******@my-deja.com> scribbled the following:

> 3. Use inline comments to refer to standards and practices,
> explain non-obvious code, or to justify a hack.
Also, if you're working on a multiple-person project, you can write
inline comments like "Fred: Please add real implementation here" or
"Are you sure THIS is what you want to do? Left unchanged just in case."
In our company, we write comments like these every now and then.

I've also worked at places where this was done, and sometimes
it escalated into arguments. Sort of like a newsgroup in the
code. :-)

I've not had arguments in code comments, but there have been two
occassions where I have had the chance to write a humorous comment.

One:
A colleague had Java code something like this:
try {
/* ... */
} catch (Exception e) {
System.err.println("Can't make hash from the password");
}
I added a comment:
// JOONAP: If you can't make hash, serve soup instead.

Two:
A colleague wrote a Javadoc comment for a method something like this:
/**
* Parses the result set returned by the JDBC API to give us some
* sensible data. Digs: row id, field type, other fields.
*/
(where "other fields" was really more names).
I added ", man." after the sentence starting with "Digs:".

--
/-- Joona Palaste (pa*****@cc.helsinki.fi) ------------- Finland --------\
\-- http://www.helsinki.fi/~palaste --------------------- rules! --------/
"Roses are red, violets are blue, I'm a schitzophrenic and so am I."
- Bob Wiley

[Mike Wahler]

"Joona I Palaste" <pa*****@cc.helsinki.fi> wrote in message
news:bp**********@oravannahka.helsinki.fi...

Mike Wahler <mk******@mkwahler.net> scribbled the following:

"Joona I Palaste" <pa*****@cc.helsinki.fi> wrote in message
news:bp**********@oravannahka.helsinki.fi...

John Bode <jo*******@my-deja.com> scribbled the following:
> 3. Use inline comments to refer to standards and practices,
> explain non-obvious code, or to justify a hack.

Also, if you're working on a multiple-person project, you can write
inline comments like "Fred: Please add real implementation here" or
"Are you sure THIS is what you want to do? Left unchanged just in case." In our company, we write comments like these every now and then.

I've also worked at places where this was done, and sometimes
it escalated into arguments. Sort of like a newsgroup in the
code. :-)

I've not had arguments in code comments, but there have been two
occassions where I have had the chance to write a humorous comment.

One:
A colleague had Java code something like this:
try {
/* ... */
} catch (Exception e) {
System.err.println("Can't make hash from the password");
}
I added a comment:
// JOONAP: If you can't make hash, serve soup instead.

Two:
A colleague wrote a Javadoc comment for a method something like this:
/**
* Parses the result set returned by the JDBC API to give us some
* sensible data. Digs: row id, field type, other fields.
*/
(where "other fields" was really more names).
I added ", man." after the sentence starting with "Digs:".

We think much alike. :-)

But I'd have probably jumped on the obvious agricultural
theme consistent in 'digs', 'row' and 'field', e.g. "Let's
farm this part out to somebody else." :-)

-Mike

[Mark McIntyre]

On Tue, 18 Nov 2003 22:03:45 GMT, in comp.lang.c , "Mike Wahler"
<mk******@mkwahler.net> wrote:

"Joona I Palaste" <pa*****@cc.helsinki.fi> wrote in message
news:bp**********@oravannahka.helsinki.fi...

John Bode <jo*******@my-deja.com> scribbled the following:

> 3. Use inline comments to refer to standards and practices,
> explain non-obvious code, or to justify a hack.

Also, if you're working on a multiple-person project, you can write
inline comments like "Fred: Please add real implementation here" or
"Are you sure THIS is what you want to do? Left unchanged just in case."
In our company, we write comments like these every now and then.

I've also worked at places where this was done, and sometimes
it escalated into arguments. Sort of like a newsgroup in the
code. :-)

I had a guy come for an interview, armed with some printouts of some
of my comments from a project I'd worked on some years earlier.
Comments like "This is a complete hack, but it works for all cases I
tested, and for the rest the punters won't be able to tell the
difference" .... :-)

--
Mark McIntyre
CLC FAQ <http://www.eskimo.com/~scs/C-faq/top.html>
CLC readme: <http://www.angelfire.com/ms3/bchambless0/welcome_to_clc.html>

[Stig Brautaset]

Mark McIntyre <ma**********@spamcop.net> wrote:

I've also worked at places where this was done, and sometimes
it escalated into arguments. Sort of like a newsgroup in the
code. :-)

I had a guy come for an interview, armed with some printouts of some
of my comments from a project I'd worked on some years earlier.
Comments like "This is a complete hack, but it works for all cases I
tested, and for the rest the punters won't be able to tell the
difference" .... :-)

So... did he get the job? :)

Stig

--
brautaset.org

[Christopher Benson-Manica]

Mark McIntyre <ma**********@spamcop.net> spoke thus:

I had a guy come for an interview, armed with some printouts of some
of my comments from a project I'd worked on some years earlier.
Comments like "This is a complete hack, but it works for all cases I
tested, and for the rest the punters won't be able to tell the
difference" .... :-)

So basically you're renouncing any further ability to mock other
people who post here with code that is no better than a cheap hack?
;)

while( 1 ) {
if( 1 ) {
while( 1 ) {
if( 0 ) {
break;
}
else {
continue;
}
continue;
}
break;
}
else if( 0 ) {
break;
}
goto 2;
}

2: printf( "%s\n", 1?0?1?"continue":"break":"continue":"break" );

--
Christopher Benson-Manica | I *should* know what I'm talking about - if I
ataru(at)cyberspace.org | don't, I need to know. Flames welcome.

[Joona I Palaste]

Joona I Palaste <pa*****@cc.helsinki.fi> scribbled the following:

Mike Wahler <mk******@mkwahler.net> scribbled the following:

"Joona I Palaste" <pa*****@cc.helsinki.fi> wrote in message
news:bp**********@oravannahka.helsinki.fi...

John Bode <jo*******@my-deja.com> scribbled the following:
> 3. Use inline comments to refer to standards and practices,
> explain non-obvious code, or to justify a hack.

Also, if you're working on a multiple-person project, you can write
inline comments like "Fred: Please add real implementation here" or
"Are you sure THIS is what you want to do? Left unchanged just in case."
In our company, we write comments like these every now and then.

I've also worked at places where this was done, and sometimes
it escalated into arguments. Sort of like a newsgroup in the
code. :-)

I've not had arguments in code comments, but there have been two
occassions where I have had the chance to write a humorous comment. One:
A colleague had Java code something like this:
try {
/* ... */
} catch (Exception e) {
System.err.println("Can't make hash from the password");
}
I added a comment:
// JOONAP: If you can't make hash, serve soup instead. Two:
A colleague wrote a Javadoc comment for a method something like this:
/**
* Parses the result set returned by the JDBC API to give us some
* sensible data. Digs: row id, field type, other fields.
*/
(where "other fields" was really more names).
I added ", man." after the sentence starting with "Digs:".

Here's a real-life Javadoc comment I wrote for a method in a class in
our application:

/**
* Returns the value of the HTTP header <code>Content-Disposition</code>.
* This header is needed to make Microsoft Internet Explorer realise that
* what we are giving it really <b>is</b> a PDF file, although it looks like
* a PDF file. Right. If Microsoft would stick to standards, we wouldn't
* have to do this, but then they wouldn't be Microsoft.<br/>
* I <b>hope</b> this works. I don't have Microsoft Internet Explorer to test
* this on.
* @param fileName The name of the file we're giving as a PDF.
* @return The value of the <code>Content-Disposition</code> HTTP header.
* @author Joona Palaste
*/

--
/-- Joona Palaste (pa*****@cc.helsinki.fi) ------------- Finland --------\
\-- http://www.helsinki.fi/~palaste --------------------- rules! --------/
"The trouble with the French is they don't have a word for entrepreneur."
- George Bush

[Marcus Lessard]

"Christian Bau"

Maybe a little OT, but I want a C specific viewpoint. Also, are there tools similar to JavaDoc for C?

There is this but I've never used it:

http://www.stack.nl/~dimitri/doxygen/

ML