Comments to explain declarations

Discussion in 'C Programming' started by pozz, Oct 21, 2012.

  1. pozz

    pozz Guest

    What is, in your opinion, the best comment layout to explain and
    describe the declarations of functions, macro, variables and so on?

    I mean where you explain what is the purpose of the function, what are
    the input paramteres (and their constrain) and the return value.

    Do you prefer to insert these comments in the .h file (for external
    symbols, of course) or in the .c file?
    pozz, Oct 21, 2012
    #1
    1. Advertising

  2. pozz

    Ian Collins Guest

    On 10/21/12 19:36, pozz wrote:
    > What is, in your opinion, the best comment layout to explain and
    > describe the declarations of functions, macro, variables and so on?


    Whatever style is use in the code you are working on. If it is your
    code, pick a style you like and stick with it.

    > I mean where you explain what is the purpose of the function, what are
    > the input paramteres (and their constrain) and the return value.
    >
    > Do you prefer to insert these comments in the .h file (for external
    > symbols, of course) or in the .c file?


    Whatever the user needs to know belongs in the public interface: the
    header. Whatever the maintainer needs to know should go with the source.

    --
    Ian Collins
    Ian Collins, Oct 21, 2012
    #2
    1. Advertising

  3. pozz

    James Kuyper Guest

    On 10/21/2012 02:45 AM, Ian Collins wrote:
    > On 10/21/12 19:36, pozz wrote:
    >> What is, in your opinion, the best comment layout to explain and
    >> describe the declarations of functions, macro, variables and so on?

    >
    > Whatever style is use in the code you are working on. If it is your
    > code, pick a style you like and stick with it.


    He's asking for advice on what style he should pick. "pick a style"
    isn't particularly responsive to that request.
    --
    James Kuyper
    James Kuyper, Oct 21, 2012
    #3
  4. pozz

    James Kuyper Guest

    On 10/21/2012 02:36 AM, pozz wrote:
    > What is, in your opinion, the best comment layout to explain and
    > describe the declarations of functions, macro, variables and so on?


    My preference is:
    1. A short descriptive comment immediately after each variable, typedef
    or macro declaration or definition, on the same line if possible,
    otherwise on the next line. If forced to put it on the next line, I
    follow the comment with a blank line to make it clear that it describes
    the preceding line, rather than the following one.
    2. A longer comment immediately after the declaration of a function
    describing what the function does.
    3. A revision history section at the top of a file starting with
    // $Log:$
    which is filled in automatically with my check-in comment when I use RCS
    to check my code in. If you use a different system for version control,
    you probably need to handle the revision history differently.

    > I mean where you explain what is the purpose of the function, what are
    > the input paramteres (and their constrain) and the return value.
    >
    > Do you prefer to insert these comments in the .h file (for external
    > symbols, of course) or in the .c file?


    The *.h file should contain comments oriented toward the user of the
    function. The *.c file should contain comments oriented to the
    maintainer of the function. In particular, there should be comments in
    the body of a function explaining anything that's not immediately
    obvious. Since lots of things seem obvious to the writer of code that
    are not necessarily obvious to the reader, those comments tend to be
    sparser than they should be. On the other hand, I seen comments like the
    following:

    profit = revenue - expenses;
    // Subtract expenses from revenue, giving profit.

    The mechanics of the code is usually obvious (you should consider
    re-writing it if that's not the case), and therefore should not need a
    comment. It's the meaning that is sometimes less obvious, and needs to
    be explained.
    --
    James Kuyper
    James Kuyper, Oct 21, 2012
    #4
  5. > What is, in your opinion, the best comment layout to explain and describe
    > the declarations of functions, macro, variables and so on?


    Consider doxygen.
    Example: http://en.wikipedia.org/wiki/Doxygen

    Leo Havmøller.
    Leo Havmøller, Oct 21, 2012
    #5
  6. pozz

    ImpalerCore Guest

    On Oct 21, 2:36 am, pozz <> wrote:
    > What is, in your opinion, the best comment layout to explain and
    > describe the declarations of functions, macro, variables and so on?
    >
    > I mean where you explain what is the purpose of the function, what are
    > the input paramteres (and their constrain) and the return value.
    >
    > Do you prefer to insert these comments in the .h file (for external
    > symbols, of course) or in the .c file?


    I'm a big fan of Doxygen style comments. The ability to browse
    library or application API in a web browser is a huge improvement to
    learn someone else's code.

    Here is an example style that I use.

    /*!
    * \brief Determine the length of a string in a fixed width buffer.
    * \param str A C string.
    * \param n The maximum length of the array pointed to by \c str.
    * \return The length of \c str, or \c n if no nul character was
    * found in the first \c n characters of \c str.
    *
    * The \c c_strnlen function returns the number of characters in the
    * string pointed to by \c str, not including the terminating nul
    * character. In doing this, \c c_strnlen looks only at the first
    * \c n characters in \c str and never past <tt>str + n</tt>.
    *
    * The motivation for \c c_strnlen is to check the string length in
    * a fixed width buffer that is filled with arbitrary data that may
    * not have a terminating nul character.
    *
    * \usage
    * \include strops/c_strnlen_example.c
    *
    * The example above should display the following.
    *
    * \code
    *
    -------------------------------------------------------------------------
    * | Example | strlen | Buffer |
    c_strnlen |
    *
    -------------------------------------------------------------------------
    * strnlen 7 strnlen............. 7
    * 1234567890 10 1234567890.......... 10
    * abcdefghijklmnopqrstuvwxyz 26 abcdefghijklmnopqrst 20
    * Real coders don't comment 25 Real coders don't co 20
    * 0 .................... 0
    * \endcode
    */
    size_t c_strnlen( const char* str, size_t n );

    The '\usage' is a macro in doxygen to display something to the effect
    of '<b>Usage:</b>', and I have example functions that demonstrate how
    to use the function in an example folder 'strops/
    c_strnlen_example.c' (with Makefiles to build all the example code
    source files). I manually place the result text in the documentation
    (so the stuff between \code and \endcode is copy pasted from an output
    file). In the HTML file, the example code is replaced so you can see
    an actual code example in the docs along with the resulting text.

    There are other code documentation tools, but choosing one that
    supports HTML generation is highly recommended.

    The comments exist as part of the public API, which are located in the
    header files. But at the same time, there are private comments that
    exist in the implementation '.c' that are meant for developers. It's
    also possible to place the documentation in separate files, but I
    prefer to put it in header files.

    Best regards,
    John D.
    ImpalerCore, Oct 22, 2012
    #6
    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:
    1,104
  2. Monk
    Replies:
    10
    Views:
    1,448
    Michael Wojcik
    Apr 20, 2005
  3. Osiris

    explain complex c declarations

    Osiris, May 21, 2007, in forum: C Programming
    Replies:
    2
    Views:
    349
    Osiris
    May 21, 2007
  4. Michael Elhek
    Replies:
    0
    Views:
    295
    Michael Elhek
    Apr 26, 2009
  5. Replies:
    4
    Views:
    589
    Dr John Stockton
    Jun 3, 2006
Loading...

Share This Page