C coding guidelines

[arnuld]

I have written C coding guidelines for my company. All of those
guidelines I have learned from this newsgroup. So I thought it will a be
good idea if you people can have a look and advise on improvement or
anything else:


==== The Compilation Phase ====

The default compiler that comes with Linux is gcc and System Programming
team of Phonologies uses the same. In Phonologies, we work as a part of a
team. A project is divided into difference pieces/sections and each piece
is given to each team member to code. You have to work as an independent
programmer to code that piece. All pieces are joined together to form a
complete software and they joined and then re-edited and tested many
times before finally labeled as "ready to release". To do that work
properly, we have some guidelines that reduce the overall bugs,
production time and of course the tension generated by future problems.
Whenever you pass a piece of code to your fellow team-mate, you pass it
after compiling and running it successfully on your machine. You will
use either "gcc -ansi -pedantic -Wall -Wextra" or "gcc -std=c99 -pedantic
-Wall -Wextra" to compile your programs. If you are interested in knowing
what *exactly* all of those flags do, please refer to the gcc manual. At
no point of time you will ever pass the program to anyone in the team
without using these flags. These flags will tell you about lots of bugs
and run-time problems before they even surface. It is your responsibility
to remove the bugs and clear the program of all the run-time anomalies of
your own programs, not of your team's. There are no Sir(s) in
Phonologies, there are no attitudes like "yes boss", or "Sir, you are
genius". At Phonologies we are a family, one family member will not bear
the consequences of the problems created by other member just because
that *other* member is unwilling to do hard-work. (We don't work like the
obsolete USSR). Your code, Your responsibility.



==== Team Spirit ====
When the pieces of software are combined and being tested and then if
some bugs come up and they will surely come up, then it will not be like
""Arnuld wrote this code and therefore I will not solve this bug"". We
are team, so please behave like a team. The reply ""Sumit wrote this
code, so he knows better about it and he can fix it sooner than me"" is
very different from the former. Now if somehow, Sumit is working on
fixing some other important issues and handling some other tasks which
have priority then you will fix this bug. Yes..., you can go and talk to
him (when he will have free time) about his design, code and the way he
programmed this piece but since he does not have time, it is you who will
fix the current bug. One of our ex-employees *Saurabh Nirkhey* worked
hard on flourishing this team-spirit.


==== Practices that are Frowned Upon ====

" void main() ": "main()" will always return int. You will never use
"void main()". If you are still using "void main()" and wonder about this
guideline then trust me you are still living in academic world. Wake up
and deal with the reality, use "int main(void)" or "int main(int argc,
char* argv[])". Every C program returns a value to the shell that helps
in knowing the reasons of success or failure or sudden crash or even
semantic errors. When you write "void main()" you *specifically* tell
the shell that you are more intelligent than "Donald Knuth" and do not
need to know the cause of the problem, that you are exceptionally
intelligent and you don't need any help from the compiler to solve the
problem. I am sorry, we do, not everyone is as intelligent as you, we
need to identify and fix the problems without wasting any time or
efforts. Hence we need "int main(void)" or "int main(int argc, char*
argv)". You may wonder that we use "int main(void)" rather than "int main
()". Its because, in C, an empty parenthesis means you can pass unlimited
number of arguments to the function. To tell the C compiler that you are
not expecting an argument you write void in those parenthesis. (In C++ an
empty parenthesis means no arguments are being passed, C and C++ are not
same languages, remember this)


"Not Function Parameters": Always check function parameters for NULL
values. You must check for unexpected values before you start to use
them. Any code that does not do so will not pass Phonologies Coding
Standards and hence will be returned back to you in no time and with no
mercy. Be a good neighbor.


"Sir, Arrays and Pointers are same": Dream on.


=== gcc Warnings ===

Here we will discuss about gcc compile-time warnings. Here is the real-
life run of "app_voiceXML.c" that we use with [[http:"www.asterisk.org/ |
Asterisk]].


my-Test.c: In function wait_for_answer:
my-Test.c:962: warning: implicit declaration of function
senddialevent
my-Test.c:966: warning: implicit declaration of function get_cid_name
my-Test.c:966: warning: passing argument 3 of ast_set_callerid makes
pointer from integer without a cast
my-Test.c:1133: warning: implicit declaration of function
onedigit_goto
my-Test.c: In function VoiceXML_exec:
my-Test.c:1261: warning: assignment discards qualifiers from pointer
target type
my-Test.c:1272: warning: assignment discards qualifiers from pointer
target type
my-Test.c:1284: warning: assignment discards qualifiers from pointer
target type
my-Test.c:1295: warning: assignment discards qualifiers from pointer
target type
my-Test.c:1306: warning: assignment discards qualifiers from pointer
target type
my-Test.c:1320: warning: assignment discards qualifiers from pointer
target type
my-Test.c:1354: warning: unused variable end
my-Test.c:1354: warning: unused variable content
my-Test.c:1534: warning: unused variable dummy
my-Test.c:1653: warning: too many arguments for format
my-Test.c:1847: warning: passing argument 3 of ast_call makes integer
from pointer without a cast
my-Test.c:1879: warning: implicit declaration of function
send_ipx_transfer_result
my-Test.c:1932: warning: implicit declaration of function sprint
my-Test.c:1852: warning: unused variable peerflag
my-Test.c:1774: warning: unused variable who
my-Test.c:1773: warning: unused variable f
my-Test.c:1252: warning: unused variable cat
my-Test.c: At top level:
my-Test.c:2101: warning: return type defaults to int
my-Test.c:2101: warning: no previous prototype for
send_ipx_transfer_result
my-Test.c: In function recv_ack_initial_sdp:
my-Test.c:736: warning: control reaches end of non-void function
my-Test.c: In function send_ipx_transfer_result:
my-Test.c:2117: warning: control reaches end of non-void function
my-Test.c: At top level:
my-Test.c:419: warning: print_proto_packet defined but not used
my-Test.c:517: warning: recv_ack_prepare defined but not used
my-Test.c:764: warning: send_ipx_prepare defined but not used



You will never ever discard the gcc warning. Warnings like:

* "passing argument 3 of ast_call makes integer from pointer without a
cast" almost always results in run-time [[http:"en.wikipedia.org/wiki/
Logic_error | semantic error]] that can take days and even months to
solve.

* "control reaches end of non-void function " will result in problems
like return value of a function was going to be passed to some other
function or to be assigned to some variable but function did not return
anything which will again cause run-time semantic error.

* "send_ipx_prepare defined but not used" . You can ignore it but you
will not. The point is, if there are too many unused variables then some
important warning, for which very few words appear on the screen, can be
lost between the mess of these unused variables. So you have to remove
all the unused variables before you pass this file to the teammate. BTW,
if you are not using a variable whats the point of defining it ? ..
Don't give me the crap that it can be used in future. In future if it
some change/edit is going to be made then we *have to* open and read the
file anyway. We can add your unused variable at that time. Things change
a lot in future, not to mention your own expansion as a programmer which
can force you to rewrite some of your programs.



==== Memory Problems ====

" malloc(), calloc()": In C we use "calloc()" or "malloc()" to allocate
memory. Please avoid them most of the time as using "malloc()" is a CPU
intensive task. When you want to work efficiently, you use static memory.
Hence we advocate the use of Static arrays rather than "malloc()". Of
course, when you need "caloc()" or "malloc()", you definitely have to use
it. Whenever you use memory allocation you will always check the return
value against NULL. Many Segmentation Faults can be avoided by using this
principle. When a Segmentation Fault comes, it does not tell you from
where it came. Out of all those 16 source files and in those 6000 lines
of code, you have no idea which one produced the Segmentation Fault.
Checking for a NULL can avoid those bitter times that every programmer
does not want to have in his life. A Segfault is PITN (Pain In The Neck),
it kills time, resources, spreads confusion, is the devotee of a Satan,
is the Diabetes of C program, is the Angel of Death. Please check your
return value if you want to keep your program alive and well. A simple
NULL check takes around 60 seconds to type but it can save days and even
months of debugging. If you count the number of seconds a team of C
Programmers has taken to solve Segfaults, they add up to years of
lifetime and its not an exaggeration.

"Memory Leaks": First make sure you have called "free()" for every "malloc
()" (unless there is some special reason on not to). Then even if your
program is eating up memory, use "valgrind": *valgrind* "--leack-
check=full --show-reachable=yes executable". "valgrind" is unavoidable
when several people are writing code for same piece of software. If you
need to use "valgrind" for your program which has only 6 C source files,
where every expression was written by you , then your programming habits
are much worse. You get that because don't understand at least one of
them: "arrays", "pointers", "malloc()" or "Data Structure" you are using.


==== Return values from functions ====

Every function who is doing an important work will always return some
value. Functions who just print information to some file or to the stdout
need not to return anything (though you may do that). The problem that we
are trying to solve is, some variable was supposed to get some value from
the function but function returns void and then that variable can wrongly
be set to some garbage value (technically known as uninitialized value)
which create havoc on your output. This can save you from a lot of
trouble. We are not saying functions can not return void, yes they can
and they are very few. Its a style of programming that helps debugging
and solving problems.


===== Work Environment =====
System Programmers who either blame someone else or or use social or
diplomatic skills to hide behind their mistakes will not be tolerated. We
strive to have a casual atmosphere so that people can code and use their
time effectively, we do our best to give programmers a sane environment
so that they can use their skills without wasting either time or efforts
and produce quality code in the end. Such kind of work environment is
very difficult to find. So please lets keep it that way or make it better.


==== One Last Piece of Advice ====

Never *ever* underestimate gcc warnings. Don't blame the compiler for
your wrongdoings. A compiler always does what you tell it to do, it is
never wrong.

 

[Nick Keighley]

I have written C coding guidelines for my company. All of those
guidelines  I have learned from this newsgroup. So I thought it will a be
good idea if you people can have a look and advise on improvement or
anything else:

==== The Compilation Phase ====

The default compiler that comes with Linux is gcc and System Programming
team of Phonologies uses the same. In Phonologies, we work as a part of a
team. A project is divided into difference pieces/sections and each piece
is given to each team member to code. You have to work as an independent
programmer to code that piece. All pieces are joined together to form a
complete software and they joined and then re-edited and tested many
times before finally labeled as "ready to release". To do that work
properly, we have some guidelines that reduce the overall bugs,
production time and of course the tension generated by future problems.
Whenever you pass a piece of code to your fellow team-mate, you pass it
after compiling and running it successfully on your machine.  You will
use either "gcc -ansi -pedantic -Wall -Wextra" or "gcc -std=c99 -pedantic
-Wall -Wextra" to compile your programs. If you are interested in knowing
what *exactly* all of those flags do, please refer to the gcc manual. At
no point of time you will ever pass the program to anyone in the team
without using these flags. These flags will tell you about lots of bugs
and run-time problems before they even surface. It is your responsibility
to remove the bugs and clear the program of all the run-time anomalies of
your own programs, not of your team's. There are no Sir(s) in
Phonologies, there are no attitudes like "yes boss", or "Sir, you are
genius". At Phonologies we are a family, one family member will not bear
the consequences of the problems created by other member just because
that *other* member is unwilling to do hard-work. (We don't work like the
obsolete USSR). Your code, Your responsibility.

I'd prefer it if something labelled a "programming standard" was
actually a programming standard and not philosophical treatise. If
you want the company bullshit/apple pie can't you at least keep it
short? It could probably do with a proof read to reduce the number
of odd grammatical constructions

==== Team Spirit ====

<snip bullshit>

where's the beef?

==== Practices that are Frowned Upon  ====

" void main() ":  "main()" will always return int. You will never use
"void main()". If you are still using "void main()" and wonder about this
guideline then trust me you are still living in academic world.

not in any academic world I've been it.

<snip>

You don't need a paragraph to justify a rule like this

"The main function shall be prototyped "int main (void)" or
"int main (int argc, int *argv[])" or equivalent. Ref C Standard"

Keep it short keep it snappy. Richard' suggestion of adopting an
existing standard would save you much pain.


<snip>

 

[bartc]

I have written C coding guidelines for my company. All of those

" void main() ": "main()" will always return int. You will never use
"void main()". If you are still using "void main()" and wonder about
this guideline then trust me you are still living in academic world.
Wake up and deal with the reality, use "int main(void)" or "int
main(int argc, char* argv[])". Every C program returns a value to the
shell that helps in knowing the reasons of success or failure or
sudden crash or even semantic errors. When you write "void main()"
you *specifically* tell the shell that you are more intelligent than
"Donald Knuth" and do not need to know the cause of the problem, that
you are exceptionally intelligent and you don't need any help from
the compiler to solve the problem. I am sorry, we do, not everyone is
as intelligent as you, we need to identify and fix the problems
without wasting any time or efforts. Hence we need "int main(void)"
or "int main(int argc, char* argv)". You may wonder that we use "int
main(void)" rather than "int main ()". Its because, in C, an empty
parenthesis means you can pass unlimited number of arguments to the
function. To tell the C compiler that you are not expecting an
argument you write void in those parenthesis. (In C++ an empty
parenthesis means no arguments are being passed, C and C++ are not
same languages, remember this)

You do realise that the main() declaration only amounts to at most one line
of a million-line application?

 

[arnuld]

The best advice I can think of is to remove lines 1 to 250 and replace
them with an existing well-known set of guidelines (e.g. Indian Hill,
easily found on the Web). Despite the inevitability of imperfection,
they are likely to be a reasonable starting point. Adopt them, and then
modify any particular guideline only after formal discussion with and
approval by the best half-dozen programmers on the team.

Okay, I got the updated version of Indian Hill C guidelines here: http://
www.psgd.org/paul/docs/cstyle/cstyle.htm

I will read it.

 

[arnuld]

You do realise that the main() declaration only amounts to at most one

line of a million-line application?

Yes and these guidelines were meant for my company, not a general guide
for a newbie. Actually, I have to rewrite/modify lots of code written by
other people in other pieces of softwares. So I have to see main() many
times.

 

[arnuld]

I'd prefer it if something labelled a "programming standard" was
actually a programming standard and not philosophical treatise. If
you want the company bullshit/apple pie can't you at least keep it
short?  It could probably do with a proof read to reduce the number
of odd grammatical constructions

Seems like you want me to modify my technical-writing skills

not in any academic world I've been it.

In Indian Education system, in Punjab School Education Board (where I
did my graduation) or Kurukshetra University from where my friend did
his Masters or in around 10 Engg. colleges from where my other friends
(old classmates) did their Bachelors of Technology and Bachelors of
Engineering, at *all* of those places me and they were taught to write
void main(). It was CLC who taught me, very first time in my life, to
use int main(void). No, I am not moaning about it (I moan about it on
my blog).

I am just trying to tell you in Indian schools (as of 2009) teachers
teach their students to write void main() and they recommend the books
who use void main() or other stupid things. Herbert Schildt was one of
the popular authors to learn from during my graduation. My teachers
told me that he was the best selling author on C and C++ and Wikipedia
conforms that.

"The main function shall be prototyped "int main (void)" or
"int main (int argc, int *argv[])" or equivalent. Ref C Standard"

Keep it short keep it snappy. Richard' suggestion of adopting an
existing standard would save you much pain.

I get your point or keeping things concise. BTW, Whats the difference
between saying:

"main() should be used as int main(void)"

and
"main() should be prototyped as int main(void)"

 

[Walter Banks]

In Indian Education system, in Punjab School Education Board (where I
did my graduation) or Kurukshetra University from where my friend did
his Masters or in around 10 Engg. colleges from where my other friends
(old classmates) did their Bachelors of Technology and Bachelors of
Engineering, at *all* of those places me and they were taught to write
void main(). It was CLC who taught me, very first time in my life, to
use int main(void).

If you are writing code for embedded systems main will never return and it is appropriate to write void main (void). The C standard says that main will return an int.

Regards,

 

[Nick Keighley]

I'd prefer it if something labelled a "programming standard" was
actually a programming standard and not philosophical treatise. If
you want the company bullshit/apple pie can't you at least keep it
short?  It could probably do with a proof read to reduce the number
of odd grammatical constructions

Seems like you want me to modify my technical-writing skills

not in any academic world I've been it.

In Indian Education system, in Punjab School Education Board

"The main function shall be prototyped "int main (void)" or
"int main (int argc, int *argv[])" or equivalent. Ref C Standard"

Keep it short keep it snappy. Richard' suggestion of adopting an
existing standard would save you much pain.

I get your point or keeping things concise. BTW, Whats the difference
between saying:

"main() should be used as int main(void)"

 and
"main() should be prototyped as int main(void)"

not much really. Mine was a bit more standardese, though maybe harder
to read for that. I was more trying to make the point that it could
be said in two lines rather than a paragraph. If you need to argue/
explain
then put that in a separate "rationale".

 

[Nick Keighley]

If you are writing code for embedded systems main will never return and it is appropriate to write void main (void). The C standard says that main will return an int.

not necessarily. There may be no main at all in that case!

 

[cognacc]

You say you have a good team spirit in the company .
But try and reread the text,.
I at least find many seemingly condescending err. "expressions"

Maybe its your humor, but be aware that it could create resistance
when "talking down" to your colleagues. or if it is
felt that you do it, even though you don't mean it that way.

like.
"will not be tolerated"
or
"Don't give me the crap that it can be used in future. In future if it
some change/edit is going to be made then we *have to* open and read
the
file"


and a lot more.

from your writing, i would think that you have a lacking team spirit
in your company.
you cannot force it, by writing "Have good teamspirit, dammit!"

And my first impression was pheew they must have some work
environmental issues?!

You are far to longwinded when explaining reasons, and they also come
out repeatabingly.
Which is annoying.


mic

 

[Keith Thompson]

If you are writing code for embedded systems main will never return
and it is appropriate to write void main (void). The C standard says
that main will return an int.

If you work on embedded systems (or, as the standard says,
freestanding implementations), the program entry point needs to be
whatever the implementation's documentation says it is.

I work on embedded systems where the main function *does* return,
but it's not called "main" (C++, not C, but it's the same idea).

 

[Chris H]

Okay, I got the updated version of Indian Hill C guidelines here: http://
www.psgd.org/paul/docs/cstyle/cstyle.htm

Try the MISRA-C coding guidelines.

 

[Jens Thoms Toerring]

I have written C coding guidelines for my company. All of those
guidelines I have learned from this newsgroup. So I thought it will a be
good idea if you people can have a look and advise on improvement or
anything else:

A few more nitpicks on top of what others have already written:

==== Memory Problems ====

" malloc(), calloc()": In C we use "calloc()" or "malloc()" to allocate
memory. Please avoid them most of the time as using "malloc()" is a CPU
intensive task. When you want to work efficiently, you use static memory.
Hence we advocate the use of Static arrays rather than "malloc()".

I don't think that's a very good guideline. malloc() may have been
slow in the past but lots of work has been spend over the last three
decades on making it as fast as possible. And static arrays have their
own problems, namely putting artificial limits on what your program
can deal with. I much prefer to use malloc() unless I can definitely
say in advance how much memory I need. And if you should run into
performance issues you still can profile the application to see if
the use of malloc() in certain places is slowing things down too
much.

Of course, when you need "caloc()" or "malloc()", you definitely have to
use it. Whenever you use memory allocation you will always check the
return value against NULL.

Good advice.

Many Segmentation Faults can be avoided by using this
principle.

That I very much doubt. Actually, a lot of programs will hardly
ever need that much memory that malloc() fails. Segmentation
faults are the result of stray pointers and there are infinitely
more ways to get a stray pointer than from a NULL returned by
malloc().

When a Segmentation Fault comes, it does not tell you from
where it came. Out of all those 16 source files and in those 6000 lines
of code, you have no idea which one produced the Segmentation Fault.
Checking for a NULL can avoid those bitter times that every programmer
does not want to have in his life.

No, it rarely can since there that so many more ways to mess up
with pointers (actually, if a pointer is NULL instead of some bad
but innocent looking value it's usually relatively straight forward
to figure out what went wrong). Only careful programming can help
in avoiding segmentation faults (and only having been bitten badly
by them tends to make you a more careful programmer;-)

==== Return values from functions ====

Every function who is doing an important work will always return some
value. Functions who just print information to some file or to the stdout
need not to return anything (though you may do that). The problem that we
are trying to solve is, some variable was supposed to get some value from
the function but function returns void and then that variable can wrongly
be set to some garbage value

That can easily be avoided by enforcing that a prototype for
a function is in scope (e.g. with -Wmissing-prototypes for gcc).
Then the compiler can warn you if you try to use a return value
from a function that doesn't return anything.

I would subscribe to your rule of "each function has to has a
return value" if you would have made that part of a plan for
error checking in your applications, i.e. that each function
(or at least all that can fail) have to return some status that
the caller is supposed to check. But any mentioning of consis-
tent errorchecking and handling is sourly missing from your
guidelines, even though this is a topic that IMHO is extremely
mportant. Programs that stick their heads in the sand and assume
that errors won't happen easily become a nightmare. And dealing
with errors in a reasonable way is nearly impossible to fit onto
an already existing code base just on afterthought. Thus I would
strongly recommend that you try to come up with a scheme for
error handling to be consistently used throughout the whole
application and that's flexible and, at the same time, simple
enough that people aren't tempted too much to "forget" about it.

Another thing I also am missing is some rules of thumb about
things like the length of functions. You seem to assume that
you will have to deal with programmers with rather limited
experience. And these are the ones I suspect to be those most
likely to come up with "monster functions", i.e. functiosn
hundreds or even thousands of lines long (at least I was
guilty of that when I was younger;-) Thus it would seem to
me to be a good idea to explictely spell out that functions
should be short and deal with one problem only (or call other
functions to handle sub-problems). Of course, when writing
many functions the question of unnecessary code duplication
is raising it's head. There's no positive effect in everyone
writing his/her own function for e.g. opening a file, re-
moving trailing spaces from a string etc. There should be a
pool of utility functions for such common tasks. But to get
people to use them they need to be well documented and the
documentation must be easily accessible for everyone. (And
to figure out what should go into that pool of utility func-
tion you need to get people to talk to each other!)

What also could be useful in the long run is a convention for
naming variables etc. How do you make global variables or
macros stand out? What are good function names? Everyone has
his/her own ideas on this but if a lot of people collaborate
on a larger project I would think that having some common
standards might be a good idea.

And then there's of course the question of documentation.
Should it be made mandatory that each function has a comment
header that lists the input arguments, the return value,
tells if it allocates memory the caller has to free() and,
unless the function is trivial to understand or very appro-
priately named, some explanation of what it's doing?

For my feeling you're sticking to too many details with your
guideline (how many 'void main()' can be in a program?) while
not addressing a lot of topics that are much more important
when writing a large application. And once 50,000 lines of code
have been written without some good conventions and rules that
everyone is following most of the time it's going to be extremely
expensive and tedious to clean up the mess - but without that
further deve- lopment will also be very expensive and tedious...

I am sympathetic with what others have written concering the
tone of your guidelines: your repeated insistence on "where a
nice company" and "we respect our co-workers", "we are just a
big family" etc. makes one wonder immediately why this has to
be repeated over and over again - if it's true you don't have
to spell it out since everyone's going to notice it. My sus-
picion would be that the more this kind of of stuff gets re-
peated the less it's true - but then I could have become too
cynical;-)
Regards, Jens

 

[Flash Gordon]

not necessarily. There may be no main at all in that case!

Or the implementation might document that main returns an int (I believe
the TMS320C25 documentation used to, in fact it used to include a copy
of K&R2, which was the first copy of it I obtained!

 

[Nick Keighley]

arnuld <[email protected]> wrote:

[...] There's no positive effect in everyone
writing his/her own function for e.g. opening a file, re-
moving trailing spaces from a string etc. There should be a
pool of utility functions for such common tasks.

I don't think there should be *a* pool of utility functions.
Or rather there shouldn't be a big pile named "utilities"
there should be a collection of libraries. String handling and
file handling should be seperated.

But to get
people to use them they need to be well documented and the
documentation must be easily accessible for everyone. (And
to figure out what should go into that pool of utility func-
tion you need to get people to talk to each other!)

What also could be useful in the long run is a convention for
naming variables etc. How do you make global variables or
macros stand out? What are good function names? Everyone has
his/her own ideas on this but if a lot of people collaborate
on a larger project I would think that having some common
standards might be a good idea.

And then there's of course the question of documentation.
Should it be made mandatory that each function has a comment
header that lists the input arguments, the return value,

no! no!! no!!!

why repeat stuff you find out by reading the prototype?
A good, short summary of the intent of the function, yes.

tells if it allocates memory the caller has to free() and,
unless the function is trivial to understand or very appro-
priately named, some explanation of what it's doing?

For my feeling you're sticking to too many details with your
guideline (how many 'void main()' can be in a program?) while
not addressing a lot of topics that are much more important
when writing a large application. And once 50,000 lines of code
have been written without some good conventions and rules that
everyone is following most of the time it's going to be extremely
expensive and tedious to clean up the mess - but without that
further deve- lopment will also be very expensive and tedious...

I am sympathetic with what others have written concering the
tone of your guidelines: your repeated insistence on "where a
nice company" and "we respect our co-workers", "we are just a
big family" etc. makes one wonder immediately why this has to
be repeated over and over again - if it's true you don't have
to spell it out since everyone's going to notice it. My sus-
picion would be that the more this kind of of stuff gets re-
peated the less it's true - but then I could have become too
cynical;-)

The phrase "we (I) (you) simply must--" designates something
that need not be done. "That goes without saying" is a red warning.
"Of course" means you had best check it yourself. These
small-change cliches and others like them, when read correctly,
are reliable channel markers.
Lazerus Long

"All our employees are treated with respect"

 

[lovecreatesbeauty]

in comp.lang.c:

Unfortunately, MISRA-C has too many drawbacks for many purposes.  Both
versions contain too many arbitrary rules without explanation, some of
them useless or counter productive.

then how do people think about this one: http://www.kernel.org/doc/Documentation/CodingStyle

 

[bartc]

On 26 Aug, 21:53, (e-mail address removed) (Jens Thoms Toerring) wrote:

no! no!! no!!!

why repeat stuff you find out by reading the prototype?
A good, short summary of the intent of the function, yes.

Eh? The return value is an int. What does that tell you? Nothing, except it
returns a value.

You need to know the significance of the return value, such as, "returns 1
to N if it works, 0 on failure".

Maybe some of this can be part of the description, but it doesn't hurt to
formally list the arguments (or parameters) and return value. Look at some
of the MSDN docs.

 

[Tech07]

Keith Thompson said:



Example: Win32, where the entry point is WinMain.

<snip>

WinMain is not the entry point. WinMain is called by a function that that
entry point function calls. The entry points are different for: GUI
programs, console programs, DLLs.

 

[Tech07]

no! no!! no!!!

why repeat stuff you find out by reading the prototype?
A good, short summary of the intent of the function, yes.

A quest for generality is inappropriate in the above case. It depends on the
project or product. Can you imagine the Windows SDK without documentation
for every function? Similarly, the above given scenario may be appropriate
for an in-house project/product where the formal documentation is only for a
handful of present and future developers/maintainers.

 

[Jorgen Grahn]

I assume he wouldn't mind a good *long* summary if that is what it
takes ...

Eh? The return value is an int. What does that tell you? Nothing, except it
returns a value.

You need to know the significance of the return value, such as, "returns 1
to N if it works, 0 on failure".

Of course! That can be as short as "returns success" or need a long
description (for example, if it is not clear what success means).

Maybe some of this can be part of the description, but it doesn't hurt to
formally list the arguments (or parameters) and return value.

It does hurt, in my experience. If you mandate comment headings like:

Name: foo

Arguments: bar - something
baz - something
bat - something

Returns: something

then you'll never get people to document the functions properly, because
they spend themselves typing things like "len - the length". And half
the time the documentation will be outdated.

Look at some
of the MSDN docs.

I don't touch that stuff. Look at some Unix section 2 and 3 man pages
-- that's the style I prefer. For example,

...
char *strcpy(char *dest, const char *src);
...
The strcpy() function copies the string pointed to by src,
including the terminating null byte ('\0'), to the buffer pointed
to by dest. The strings may not overlap, and the destination string
dest must be large enough to receive the copy.

The big difference here is that you get to form complete sentences --
keeps you somewhat intellectually honest -- and you can describe the
parameters in terms of how they work together. With the
list-of-arguments style, you have to pretend they have nothing to do
with each other (like a pointer to a buffer and its length).

/Jorgen