Documenting C Code

J

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

Jack Klein

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
 
R

Richard Heathfield

Jeff said:
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.
 
C

Christian Bau

Jeff Rodriguez said:
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.
 
J

John Bode

Jeff Rodriguez said:
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,
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.
 
J

Joona I Palaste

John Bode said:
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.
 
M

Mike Wahler

Joona I Palaste said:
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
 
J

Joona I Palaste

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:".
 
M

Mike Wahler

Joona I Palaste said:
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
 
M

Mark McIntyre

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

Stig Brautaset

Mark McIntyre said:
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
 
C

Christopher Benson-Manica

Mark McIntyre said:
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" );
 
J

Joona I Palaste

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
*/
 
A

Anonymous

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

Bizarrely, yes. But mainly because he happened to be a pretty fine
programmer, if prone to weird stuff like knitting socks in the dealing
room.
 
A

Anonymous

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?

ah, but /that/ was when I was younger and wiser. Now I'm older and
know better... :)
 
C

Christopher Benson-Manica

Anonymous said:
ah, but /that/ was when I was younger and wiser. Now I'm older and
know better... :)

Oh, I see. So it's okay for me to produce uttertly horrific code now
as long as I see the light before I'm 30, or before I run a major
corporation (*cough* Microsoft...) ;)

void main(void) {
char *a=++(void*)(malloc('q'*sizeof(void*)));
}
 
C

CBFalconer

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

Bizarrely, yes. But mainly because he happened to be a pretty
fine programmer, if prone to weird stuff like knitting socks in
the dealing room.[/QUOTE]

What is a dealing room?
 

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

Forum statistics

Threads
473,731
Messages
2,569,432
Members
44,832
Latest member
GlennSmall

Latest Threads

Top