C style: private functions, function docstrings & style

[Ben Pfaff]

Ben Pfaff wrote, On 07/12/07 04:50:



Yes, I believe you are overstating the case. Your argument would apply
just as well to all documentation and comments in code, since comments
and documentation are only ever of use if they reflect the code
reasonably well. Doxygen documentation relies on the developers
writing it and keeping it up to date just as any other documentation
and comments in the code.

Other documentation and comments in code is not usually ripped
bodily from the code and presented as a separate document. Thus,
it is easy to sanity-check it and read between the lines by
looking at the code that is nearby.

 

[Flash Gordon]

Ben Pfaff wrote, On 07/12/07 21:11:

Other documentation and comments in code is not usually ripped
bodily from the code and presented as a separate document. Thus,
it is easy to sanity-check it and read between the lines by
looking at the code that is nearby.

Other documentation is often written before anyone considers writing a
single line of code. Requirement specifications, design specifications,
interface specifications, sometimes testing documentation etc. Also as
others have pointed out it is difficult to include graphics in a source
file. Also some people are not allowed to see the source code (because
it is not open source) or because they are doing true black-box testing
etc. In any case, as I already pointed out else-thread, if it is set up
appropriately the extracted documentation is NOT isolated from the code,
because you can have links from the documentation to the relevant
sections of the code.

 

[Tor Rustad]

I've been dev'ing in C for the past few months, and was wondering
whether there was a standard coding style for [snip] documenting
functions

Perhaps doxygen?

Is doxygen documentation ever useful? I've read through lots of
doxygen-generated documentation, but I was always left with
numerous questions that could only be answered by looking at the
source. Given that, I usually prefer to use something like
"tags" to jump directly to function definitions. If the function
has a comment at the top explaining its purpose, then that's more
convenient than looking at a separate document describing its
purpose, and the source code is right there to answer any
remaining

Somewhat similar points that Jack makes, I started using doxygen some
5-6 years ago, and have not really used the tool to it's full potential
yet, but rather used it in a way to structure comments that I anyway
would have written.

My last programming project was very XP like, the time limits where
extremely short, and the functional specs a disaster. In order to reach
delivery dates, both top-down and bottom-up programming strategies where
used (just like drilling a tunnel from both ends, and hope the two teams
link up in the middle).

Some test cases where skipped, each given a '\test' tag, where shortcuts
could be taken, a '\todo' tag was inserted, in rare cases, known bugs
was left in with a '\bug' tag. The delivery date was met, before the day
fines started running. For phase 2, we will have far better time, and
can address all those shortcuts being made. Sure we could have used
another method or documenting tool, but it was easy and efficient.

I find it an advantage, to have documentation close to the source, and
it shouldn't be necessary to read the source to interface a library API
correctly. Doxygen can generate the docs in a number of formats, and by
including the dot package, you also get those awesome looking graphs.

 

[Tor Rustad]

Hi everyone

I've been dev'ing in C for the past few months, and was wondering
whether there was a standard coding style for private functions
(function/s not defined in the header file) and documenting functions
(should this be done in the header or C file, and is there a
standard?)

doxygen is commonly used for documenting

For example: to make a function private in Python, you prefix the name
with two underscores. Python also provides a functionality called
docstrings to write doco for functions.

In C, we use *static* functions for this.

I'm looking for a generally accepted style... primarily so that I can
be a good C citizen & so the next developer doesn't want to kill
me

Look up the indent tool, here you find some common styles, including GNU
and K&R. The Linux kernel use this style:

indent -npro -kr -i8 -ts8 -sob -l80 -ss -ncs

And also, do any C developers here use camel case (popular in C#/Java)
in their day to day C coding? I notice most code in C using plenty of
underscores, so I've been keeping with that. IMHO, I prefer the look
of camel case though.

E.g. Camel case = socketDescriptor vs. underscores = socket_descriptor

In my expierence, application programmers often use long names e.g.
"SocketDescriptor", while low-level programmers use short'er names with
underscore.