Documenting C Code

Discussion in 'C Programming' started by Jeff Rodriguez, Nov 18, 2003.

  1. 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?
    Jeff Rodriguez, Nov 18, 2003
    #1
    1. Advertising

  2. Jeff Rodriguez

    Jack Klein Guest

    On Mon, 17 Nov 2003 20:34:52 -0700, Jeff Rodriguez
    <> 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
    Jack Klein, Nov 18, 2003
    #2
    1. Advertising

  3. 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 :
    "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
    Richard Heathfield, Nov 18, 2003
    #3
  4. In article <Zqgub.19692$Ro5.18776@fed1read07>,
    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?
    >


    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.
    Christian Bau, Nov 18, 2003
    #4
  5. Jeff Rodriguez

    John Bode Guest

    Jeff Rodriguez <> 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,
    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.
    John Bode, Nov 18, 2003
    #5
  6. John Bode <> 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 () ------------- 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
    Joona I Palaste, Nov 18, 2003
    #6
  7. Jeff Rodriguez

    Mike Wahler Guest

    "Joona I Palaste" <> wrote in message
    news:bpe4kd$4ti$...
    > John Bode <> 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
    Mike Wahler, Nov 18, 2003
    #7
  8. Mike Wahler <> scribbled the following:
    > "Joona I Palaste" <> wrote in message
    > news:bpe4kd$4ti$...
    >> John Bode <> 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 () ------------- Finland --------\
    \-- http://www.helsinki.fi/~palaste --------------------- rules! --------/
    "Roses are red, violets are blue, I'm a schitzophrenic and so am I."
    - Bob Wiley
    Joona I Palaste, Nov 18, 2003
    #8
  9. Jeff Rodriguez

    Mike Wahler Guest

    "Joona I Palaste" <> wrote in message
    news:bpe5id$5i8$...
    > Mike Wahler <> scribbled the following:
    > > "Joona I Palaste" <> wrote in message
    > > news:bpe4kd$4ti$...
    > >> John Bode <> 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
    Mike Wahler, Nov 18, 2003
    #9
  10. On Tue, 18 Nov 2003 22:03:45 GMT, in comp.lang.c , "Mike Wahler"
    <> wrote:

    >
    >"Joona I Palaste" <> wrote in message
    >news:bpe4kd$4ti$...
    >> John Bode <> 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>
    Mark McIntyre, Nov 18, 2003
    #10
  11. Mark McIntyre <> 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
    Stig Brautaset, Nov 19, 2003
    #11
  12. Mark McIntyre <> 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.
    Christopher Benson-Manica, Nov 19, 2003
    #12
  13. Joona I Palaste <> scribbled the following:
    > Mike Wahler <> scribbled the following:
    >> "Joona I Palaste" <> wrote in message
    >> news:bpe4kd$4ti$...
    >>> John Bode <> 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 () ------------- Finland --------\
    \-- http://www.helsinki.fi/~palaste --------------------- rules! --------/
    "The trouble with the French is they don't have a word for entrepreneur."
    - George Bush
    Joona I Palaste, Nov 19, 2003
    #13
  14. "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
    Marcus Lessard, Nov 19, 2003
    #14
  15. Jeff Rodriguez

    Anonymous Guest

    On 19 Nov 2003 09:49:47 GMT, in comp.lang.c , Stig Brautaset
    <> wrote:

    >Mark McIntyre <> wrote:
    >>
    >> 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? :)


    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.

    --
    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>
    Anonymous, Nov 19, 2003
    #15
  16. Jeff Rodriguez

    Anonymous Guest

    On Wed, 19 Nov 2003 18:05:26 +0000 (UTC), in comp.lang.c , Christopher
    Benson-Manica <> wrote:

    >Mark McIntyre <> 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?


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

    --
    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>
    Anonymous, Nov 19, 2003
    #16
  17. Anonymous <Nobody> spoke thus:

    > 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*)));
    }

    --
    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.
    Christopher Benson-Manica, Nov 20, 2003
    #17
  18. Jeff Rodriguez

    CBFalconer Guest

    Anonymous wrote:
    > On 19 Nov 2003 09:49:47 GMT, in comp.lang.c , Stig Brautaset
    > >Mark McIntyre <> wrote:
    > >>
    > >> 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? :)

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


    What is a dealing room?

    --
    Chuck F () ()
    Available for consulting/temporary embedded and systems.
    <http://cbfalconer.home.att.net> USE worldnet address!
    CBFalconer, Nov 20, 2003
    #18
    1. Advertising

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

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Replies:
    0
    Views:
    607
  2. Andre Kostur

    Re: Documenting code in c++

    Andre Kostur, Jun 30, 2003, in forum: C++
    Replies:
    0
    Views:
    375
    Andre Kostur
    Jun 30, 2003
  3. Replies:
    5
    Views:
    395
    Cedric LEMAIRE
    Sep 3, 2003
  4. Rony
    Replies:
    2
    Views:
    569
  5. Isaac Rodriguez

    Documenting Python code.

    Isaac Rodriguez, May 3, 2005, in forum: Python
    Replies:
    5
    Views:
    5,479
    Fredrik Lundh
    May 5, 2005
Loading...

Share This Page