Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > C Programming > Standard for comments prefixing a function

Reply
Thread Tools

Standard for comments prefixing a function

 
 
darkknight
Guest
Posts: n/a
 
      09-27-2005

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
 
Reply With Quote
 
 
 
 
Skarmander
Guest
Posts: n/a
 
      09-27-2005
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.
 
Reply With Quote
 
 
 
 
E. Robert Tisdale
Guest
Posts: n/a
 
      09-27-2005
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[s] 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.
 
Reply With Quote
 
John Devereux
Guest
Posts: n/a
 
      09-27-2005
Skarmander <(E-Mail Removed)> 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
 
Reply With Quote
 
rafaelolg
Guest
Posts: n/a
 
      09-28-2005
There is no standard but there is [1]Doxygen style.
http://www.stack.nl/~dimitri/doxygen/

 
Reply With Quote
 
Jack Klein
Guest
Posts: n/a
 
      09-28-2005
On Wed, 28 Sep 2005 10:18:52 +1200, darkknight <(E-Mail Removed)>
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/~a...FAQ-acllc.html
 
Reply With Quote
 
Alexei A. Frounze
Guest
Posts: n/a
 
      09-28-2005
"John Devereux" <(E-Mail Removed)> wrote in message
news:(E-Mail Removed)...
> Skarmander <(E-Mail Removed)> 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


 
Reply With Quote
 
darkknight
Guest
Posts: n/a
 
      09-28-2005
On Wed, 28 Sep 2005 10:40:52 +0400, Alexei A. Frounze wrote:

>"John Devereux" <(E-Mail Removed)> wrote in message
>news:(E-Mail Removed)...
>> Skarmander <(E-Mail Removed)> 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
 
Reply With Quote
 
Alexei A. Frounze
Guest
Posts: n/a
 
      09-28-2005
"darkknight" <(E-Mail Removed)> wrote in message
news:(E-Mail Removed)...
> 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


 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Printing a hex character and prefixing it correctly xamalek@yahoo.com Python 4 05-15-2009 05:49 PM
Routine for prefixing '>' before every line of a string Sanjay Python 5 12-16-2006 01:29 PM
A program to replace all JS comments with JSP comments in jsp files tungchau81@yahoo.com Java 0 06-02-2006 06:35 AM
Finding # prefixing numbers peterbe@gmail.com Python 3 07-19-2005 09:26 PM
Comments format: comments extending over multi-line Monk C Programming 10 04-20-2005 05:09 PM



Advertisments