C style: private functions, function docstrings & style

[Khookie]

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?)

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.

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

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

Cheers

Chris

BTW, I know there are plenty of C style guides around, but they all
seem to be very verbose - so I hope someone here can indulge my
ignorance

 

[jacob navia]

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?)

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.

1) To make a function private in C you prefix it with "static"

For instance

static int foo(int n);

The same for variables:

static int MyPrivateStuff;

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

That is the generally recommended way, i.e. the standard way
of doing that.

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

Cheers

Chris

BTW, I know there are plenty of C style guides around, but they all
seem to be very verbose - so I hope someone here can indulge my
ignorance

This is more a matter of preferences. Pick your choice and then just
stick to it.

 

[Mark Bluemel]

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 [snip] documenting
functions

Perhaps doxygen?

 

[Ben Pfaff]

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

 

[Ben Pfaff]

purpose, and the source code is right there to answer any
remaining

....questions.

 

[Keith Thompson]

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?)

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.

As jacob already said, use "static" for private functions; it means
the function's name won't be visible outside the source file in which
it's defined.

C doesn't have anything like Python's docstrings. You can just write
a comment block above the function definition. Some places will
impose a standard on how to write it. If you're not bound by such a
standard, look at some existing code and pick a style you like that
seems to convey the information a reader is likely to need.

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

Note that this applies even if you're the next developer. You can't
always avoid the "What on Earth was I *thinking* when I wrote that?"
phenomenon, but you can try.

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

Camel case doesn't seem to be very popular in C. Personally I prefer
lowercase with underscores; that's probably your safest bet. If
you're working on existing code, stick to whatever style it uses
(assuming it has a consistent style), even if you don't like it.

[...]

 

[Flash Gordon]

Ben Pfaff wrote, On 06/12/07 16:35:

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 generally find the libxml2 documentation useful and that is generated
using doxygen IIRC.

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.

That is really down to the people writing the comments that doxygen
extracts rather than a fault with doxygen itself.

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

IIRC you can have doxygen documentation that can jump you straight to a
copy of the code for perusal.

 

[Malcolm McLean]

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

I keep all functions that depend only on the standard library in lower case,
and mixed case for functions that depend on third party libraries.

So a lower case function may call only other functions in lower case.

I don't use underscores, except in namespace-protecting prefixes. eg
opt_get() for my options parser. A function simply called get() would be at
too much risk of colliding with somethign else.

 

[Ben Pfaff]

Ben Pfaff wrote, On 06/12/07 16:35:

IIRC you can have doxygen documentation that can jump you straight to
a copy of the code for perusal.

So why is that better, then, than just going straight to the
source code? The documentation is there too, since it's
generated from comments in the source code.

 

[jacob navia]

So why is that better, then, than just going straight to the
source code? The documentation is there too, since it's
generated from comments in the source code.

Exactly. I agree with you in this respect.
Many people use doxygen instead of writing the documentation
and that is ALWAYS a mistake! doxygen just reformats the
source code without adding anything new or interesting. It can be
great if you do not have a good IDE, but that is all.

 

[Flash Gordon]

jacob navia wrote, On 06/12/07 21:24:

Exactly. I agree with you in this respect.

The html version gives you hyperlinks for jumping about etc. Of course,
a good IDE might give you this as well...

Many people use doxygen instead of writing the documentation
and that is ALWAYS a mistake! doxygen just reformats the
source code without adding anything new or interesting. It can be
great if you do not have a good IDE, but that is all.

Thinking that doxygen or any other tool is a substitute for
documentation and comments is a mistake. Unfortunately it is a mistake a
lot of people make.

 

[CBFalconer]

Khookie wrote:
.... snip ...


1) To make a function private in C you prefix it with "static"

For instance
static int foo(int n);

This is OK, since functions have to be declared and are all
naturally globally accesible.

The same for variables:
static int MyPrivateStuff;

However this is flawed. Objects need to be in file scope to be so
privatized. If declared within a function they have function
scope, and the 'static' makes them permanent, i.e. not abandoned on
function exit.

 

[Ben Pfaff]

jacob navia wrote, On 06/12/07 21:24:

The html version gives you hyperlinks for jumping about etc. Of
course, a good IDE might give you this as well...

Exactly. That's one of the features I expect a decent
programmers' editor to have.

By the way: any relation to Charlie?

 

[Al Balmer]

Exactly. That's one of the features I expect a decent
programmers' editor to have.

The Slickedit editor that I use will jump to a symbol definition, or
function prototype, and will give you a list of references to any
symbol. If you hover the mouse over a symbol, it pops up the
definition of the symbol and any associated comments. For a function,
that means you can see the argument list and a comment block if
available. It will even help pick the arguments for a function call
according to type, and provide a drop-down list of the members of a
struct as soon as you type the "." or "->". I find this far more
useful for both programming and analyzing than any documentation
generator I've ever seen.

 

[Flash Gordon]

Ben Pfaff wrote, On 06/12/07 23:16:

Exactly. That's one of the features I expect a decent
programmers' editor to have.

Not everyone always has access to a decent programmers editor. doxygen
is also useful for generating documentation for people who will not have
access to the source code.

Note that I am *not* saying that doxygen is the solution to all
documentation problems. In fact, I strongly believe it is not the
solution to all problems. I just don't believe it makes matters worse or
that all documentation produced with doxygen is of no use.

By the way: any relation to Charlie?

Not that I am aware of.

 

[Pierre Asselin]

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.

Doxygen lets you embed LaTeX formulas in your comments, which can
be useful when documenting mathematical software. It also accepts
graphviz inserts ( http://www.graphviz.org/ ) so you can include
diagrams in your documentation, useful with all kinds of software.
Both are be hard to emulate with just C comments.

In addition, if you spend the effort, you can create a "mainpage"
that acts as a roadmap to your code. Like a good README file,
but again you can embed formulas and diagrams and of course you
can hyperlink to the reference portion of your docs.

It's a bit early on the learning curve for me, but I think
it has potential.

 

[Jack Klein]

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

Off-topic, of course, but we've adopted doxygen over the last several
years.

At the conclusion of a version ready to release to manufacturing, we
run the tool and all of the generated output goes into the legally
required documentation that is part of the industry that we are in.

The actual programmers never look at the tool output, yet it has real
value.

It provides a standard format for writing documentation headers for
functions, data types, macros, enums, and so on. Everyone knows the
format, and its presence and accuracy is checked during code reviews.

You seem to be missing the point that the doxygen documentation is
generated from comment blocks in the source and header files, and if
you place them properly in the header and source files, they are right
where you want them.

When I want to call your function, I merely open the header file that
prototypes it, for that is where the doxygen header is, not in the
source, and find the interface detail I need. Both I and my source
code only need to reference the prototype in the header for all the
API details.

The function definition, in its own source file, merely has a comment
block that says "see such_and_such.h for interface details", so if I
have to read your source, for code review, bug fix, feature addition,
it tells me directly what header file contains the prototype and the
doxygen comment block.

--
Jack Klein
Home: http://JK-Technology.Com
FAQs for
comp.lang.c http://c-faq.com/
comp.lang.c++ http://www.parashift.com/c++-faq-lite/
alt.comp.lang.learn.c-c++
http://www.club.cc.cmu.edu/~ajo/docs/FAQ-acllc.html

 

[Ben Pfaff]

You seem to be missing the point that the doxygen documentation is
generated from comment blocks in the source and header files, and if
you place them properly in the header and source files, they are right
where you want them.

When I want to call your function, I merely open the header file that
prototypes it, for that is where the doxygen header is, not in the
source, and find the interface detail I need. Both I and my source
code only need to reference the prototype in the header for all the
API details.

Probably, I am overstating the case. If the doxygen
documentation is written with great care, and kept up to date as
code changes, I can see that it would be useful. I do not doubt
that on a team that you or a number of other comp.lang.c regulars
were on or led, this could be the case. But in the cases where
I've encountered it, the doxygen documentation by itself is
insufficient to understand how to properly use a library, and
I've always had to resort to the source code itself.

 

[jaysome]

The Slickedit editor that I use will jump to a symbol definition, or
function prototype, and will give you a list of references to any
symbol. If you hover the mouse over a symbol, it pops up the
definition of the symbol and any associated comments. For a function,
that means you can see the argument list and a comment block if
available. It will even help pick the arguments for a function call
according to type, and provide a drop-down list of the members of a
struct as soon as you type the "." or "->". I find this far more
useful for both programming and analyzing than any documentation
generator I've ever seen.

Microsoft VC++ 6.0 (circa 1998) does all of this too. I wonder who
copied who?

--
jay

http://www.microsoft.com/express/vc/
http://www.ubuntu.com/
http://www.gimpel.com/
http://www.bullseye.com/

 

[Flash Gordon]

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

Probably, I am overstating the case. If the doxygen
documentation is written with great care, and kept up to date as
code changes, I can see that it would be useful. I do not doubt
that on a team that you or a number of other comp.lang.c regulars
were on or led, this could be the case. But in the cases where
I've encountered it, the doxygen documentation by itself is
insufficient to understand how to properly use a library, and
I've always had to resort to the source code itself.

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.