Advertisements

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.

Advertisements

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

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:

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

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.

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.

Share This Page

Welcome to The Coding Forums!

Welcome to the Coding Forums, the place to chat about anything related to programming and coding languages.

Please join our friendly community by clicking the button below - it only takes a few seconds and is totally free. You'll be able to ask questions about coding or chat with the community and help others.
Sign up now!