Standard for comments prefixing a function

Discussion in 'C Programming' started by darkknight, Sep 27, 2005.

  1. darkknight

    darkknight Guest

    Hi

    Is there any commonest practice or "industry standard" regarding
    comments that appear at the head of a function definition or function
    prototype?

    Do they go in the .c file only, the .h file only or both?

    What do the comments consist of? Pre-conditions, post-conditions,
    inputs, outputs, behaviour?

    TIA
     
    darkknight, Sep 27, 2005
    #1
    1. Advertising

  2. darkknight

    Skarmander Guest

    darkknight wrote:
    > Is there any commonest practice or "industry standard" regarding
    > comments that appear at the head of a function definition or function
    > prototype?
    >

    "Standards are fun, there are so many to choose from." So, no. Or
    rather, there are lots, but don't go looking for the ISO standard on
    comments. There's no one style that will make people go "ahh, of course".

    > Do they go in the .c file only, the .h file only or both?
    >

    Both. In the .c file they're a courtesy to maintainers. In the .h file
    they're vital to callers. Unfortunately the regular C toolchain offers
    no support for maintaining structured comments, so you're on your own
    maintaining them and making sure the header and implementation don't
    drift apart (which is lethal).

    > What do the comments consist of? Pre-conditions, post-conditions,
    > inputs, outputs, behaviour?
    >

    Yes.

    More precisely: anything you must mention for the function to be
    correctly called and the results correctly processed by an innocent
    reader, especially exceptional conditions.

    What exactly this amounts to depends on your programming culture. I
    won't delve into this issue here, since entire books must have been
    written on the subject by people far more eloquent than me, and I'm sure
    many more are eager to offer their opinions.

    I will just opine that standards must be taken with a grain of salt.
    Many value form over content and fail to impart a sense of purpose and
    perspective on the programmer. I have seen too much code that had
    comments added to it "according to the standard" that failed to convey
    necessary information that could not be derived from the declaration,
    and needlessly repeated information that could.

    S.
     
    Skarmander, Sep 27, 2005
    #2
    1. Advertising

  3. darkknight wrote:

    > Is there any commonest practice or "industry standard" regarding comments
    > that appear at the head of a function definition or function prototype?
    >
    > Do they go in the .c file only, the .h file only or both?
    >
    > What do the comments consist of?
    > Pre-conditions, post-conditions, inputs, outputs, behaviour?


    /* Find a few eigenvalues in a complex hermitian matrix
    using Lanczos' algorithm. */
    nml_extent eigenvaluesLanczos(/* number of eigenvalues actually found */
    nml_dvector *value, /* out real eigenvalue vector */
    nml_d3bands *T, /* out symmetric tridiagonal matrix */
    nml_extent *pIterations, /* out actual number of iterations */
    nml_dcvector *r_n, /* inout r_{n} = q_{n+1}*beta_{n} */
    nml_dcvector *q_n, /* inout current complex Lanczos vector*/
    nml_dcvector *q_n1, /* inout previous complex Lanczos vector*/
    nml_extent length, /* in extent of vectors r_n, q_n & q_n1 */
    nml_extent requested, /* in requested number of eigenvalues */
    int ConvCheckStartIter, /* in convergence check start iteration */
    int ConvCheckSkipRate, /* in convergence check skip rate */
    nml_extent imax, /* in maximum number of iterations + 1 */
    nml_dscalar emin, /* in eigenvalue search lower bound */
    nml_dscalar emax, /* in eigenvalue search upper bound */
    nml_dscalar tolerance, /* in eigenvalue convergence tolerance */
    nml_dscalar resolution, /* in eigenvalue separation minimum */
    void (*matmul)(const int**, nml_dcscalar*, const nml_dcscalar*),
    const int* argument[], /* matrix-vector multiply argument list */
    FILE *fp_trace, /* inout trace log text file pointer */
    FILE *fp_instant, /* inout instant log text file pointer */
    FILE *fp_log, /* inout message log text file pointer */
    int verbose /* in verbose diagnostic messages */
    );


    This is typical.
    Yes, it should appear in *both* the interface (header) file
    and in the implementation (source) file.
    Try to identify the algorithm that you are using.
    Reference a textbook or paper if necessary.
    That will save you a lot of unecessary comments.
    Pass inputs by value or const reference [pointer].
    I try to return by value but,
    when outputs must appear in the argument list,
    I like to put them first before any inputs.
    Argument names appear in the function declaration
    as well as the function definition and
    are chosen carefully to help document the argument list.
     
    E. Robert Tisdale, Sep 27, 2005
    #3
  4. Skarmander <> writes:

    > darkknight wrote:
    > > Is there any commonest practice or "industry standard" regarding
    > > comments that appear at the head of a function definition or function
    > > prototype?
    > >

    <SNIP>
    > > Do they go in the .c file only, the .h file only or both?
    > >

    > Both. In the .c file they're a courtesy to maintainers. In the .h file
    > they're vital to callers. Unfortunately the regular C toolchain offers
    > no support for maintaining structured comments, so you're on your own
    > maintaining them and making sure the header and implementation don't
    > drift apart (which is lethal).


    Just put the comments in the module header, then have the module
    source file #include them :)

    --

    John Devereux
     
    John Devereux, Sep 28, 2005
    #4
  5. darkknight

    rafaelolg Guest

    rafaelolg, Sep 28, 2005
    #5
  6. darkknight

    Jack Klein Guest

    On Wed, 28 Sep 2005 10:18:52 +1200, darkknight <>
    wrote in comp.lang.c:

    >
    > Hi
    >
    > Is there any commonest practice or "industry standard" regarding
    > comments that appear at the head of a function definition or function
    > prototype?
    >
    > Do they go in the .c file only, the .h file only or both?
    >
    > What do the comments consist of? Pre-conditions, post-conditions,
    > inputs, outputs, behaviour?
    >
    > TIA


    Multiposting, that is posting the same message individually to
    multiple newsgroups, is considered bad manners.

    The proper method for posting the same message in multiple groups,
    after making SURE it is topical in each of the groups, is to
    crosspost, that is post it once with the names of the multiple groups
    in the "newsgroups" line.

    In this particular case, I gave a detailed answer with examples in
    comp.arch.embedded, and I am not going to repeat it here.

    --
    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++
    http://www.contrib.andrew.cmu.edu/~ajo/docs/FAQ-acllc.html
     
    Jack Klein, Sep 28, 2005
    #6
  7. "John Devereux" <> wrote in message
    news:...
    > Skarmander <> writes:

    ....
    > > Both. In the .c file they're a courtesy to maintainers. In the .h file
    > > they're vital to callers. Unfortunately the regular C toolchain offers
    > > no support for maintaining structured comments, so you're on your own
    > > maintaining them and making sure the header and implementation don't
    > > drift apart (which is lethal).

    >
    > Just put the comments in the module header, then have the module
    > source file #include them :)


    Put what the caller must know in .h. Put everything else that is internal to
    the implementation and developers in .c.

    Alex
     
    Alexei A. Frounze, Sep 28, 2005
    #7
  8. darkknight

    darkknight Guest

    On Wed, 28 Sep 2005 10:40:52 +0400, Alexei A. Frounze wrote:

    >"John Devereux" <> wrote in message
    >news:...
    >> Skarmander <> writes:

    >...
    >> > Both. In the .c file they're a courtesy to maintainers. In the .h file
    >> > they're vital to callers. Unfortunately the regular C toolchain offers
    >> > no support for maintaining structured comments, so you're on your own
    >> > maintaining them and making sure the header and implementation don't
    >> > drift apart (which is lethal).

    >>
    >> Just put the comments in the module header, then have the module
    >> source file #include them :)

    >
    >Put what the caller must know in .h. Put everything else that is internal to
    >the implementation and developers in .c.



    Why should the developer have to look in both the header file and the .c
    file when examining the function implementation. The caller can just as
    easily look in the .c file for details that aren't conveyed by function
    and parameter names, as in the header file, except when a header file is
    distributed without the .c file.

    darkknight
     
    darkknight, Sep 28, 2005
    #8
  9. "darkknight" <> wrote in message
    news:...
    > On Wed, 28 Sep 2005 10:40:52 +0400, Alexei A. Frounze wrote:
    > >Put what the caller must know in .h. Put everything else that is internal

    to
    > >the implementation and developers in .c.

    >
    > Why should the developer have to look in both the header file and the .c
    > file when examining the function implementation.


    The developer must know the API. His primary code to work with is in .c
    files as it contains most of the implementation. It's fine to have a short
    function description in .c too, but then these descriptions must be
    synchronized in both .h and .c, something that needs to be automated as
    nobody wants to copy and paste the comments by hand.

    > The caller can just as
    > easily look in the .c file for details that aren't conveyed by function
    > and parameter names, as in the header file, except when a header file is
    > distributed without the .c file.


    That is only possible if the program/library is delivered with its full
    source code. Otherwise, the .h files must contain enough information for the
    caller to write the calling code.

    Alex
     
    Alexei A. Frounze, Sep 28, 2005
    #9
    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,177
  2. Replies:
    3
    Views:
    330
    Caleb Hattingh
    Jul 19, 2005
  3. Sanjay
    Replies:
    5
    Views:
    264
    Sanjay
    Dec 16, 2006
  4. Monk
    Replies:
    10
    Views:
    1,538
    Michael Wojcik
    Apr 20, 2005
  5. Replies:
    4
    Views:
    339
    Dave Angel
    May 15, 2009
Loading...

Share This Page