C coding guidelines

Discussion in 'C Programming' started by arnuld, Aug 26, 2009.

  1. arnuld

    arnuld Guest

    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.








    --
    www.lispmachine.wordpress.com
    my email is @ the above blog.
     
    arnuld, Aug 26, 2009
    #1
    1. Advertising

  2. On 26 Aug, 07:34, arnuld <> wrote:

    > 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>
     
    Nick Keighley, Aug 26, 2009
    #2
    1. Advertising

  3. arnuld

    bartc Guest

    arnuld wrote:
    > 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?

    --
    Bart
     
    bartc, Aug 26, 2009
    #3
  4. arnuld

    arnuld Guest

    > On Wed, 26 Aug 2009 07:31:40 +0000, Richard Heathfield wrote:

    > 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.





    --
    www.lispmachine.wordpress.com
    my email is @ the above blog.
     
    arnuld, Aug 26, 2009
    #4
  5. arnuld

    arnuld Guest

    > 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.





    --
    www.lispmachine.wordpress.com
    my email is @ the above blog.
     
    arnuld, Aug 26, 2009
    #5
  6. arnuld

    arnuld Guest

    > On Aug 26, 1:44 pm, Nick Keighley <> wrote:

    > 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)"
     
    arnuld, Aug 26, 2009
    #6
  7. arnuld

    Walter Banks Guest

    arnuld wrote:

    > 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,

    --
    Walter Banks
    Byte Craft Limited
    http://www.bytecraft.com
     
    Walter Banks, Aug 26, 2009
    #7
  8. On 26 Aug, 11:50, arnuld <> wrote:
    > > On Aug 26, 1:44 pm, Nick Keighley <> wrote:


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


    <snip etc>

    > > "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, Aug 26, 2009
    #8
  9. On 26 Aug, 13:12, Walter Banks <> wrote:
    > arnuld wrote:
    > > 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.


    not necessarily. There may be no main at all in that case!
     
    Nick Keighley, Aug 26, 2009
    #9
  10. arnuld

    cognacc Guest

    On Aug 26, 8:34 am, arnuld <> wrote:

    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
     
    cognacc, Aug 26, 2009
    #10
  11. Walter Banks <> writes:
    > arnuld wrote:
    >> 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.


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

    --
    Keith Thompson (The_Other_Keith) <http://www.ghoti.net/~kst>
    Nokia
    "We must do something. This is something. Therefore, we must do this."
    -- Antony Jay and Jonathan Lynn, "Yes Minister"
     
    Keith Thompson, Aug 26, 2009
    #11
  12. arnuld

    Chris H Guest

    In message <>, arnuld
    <> writes
    >> On Wed, 26 Aug 2009 07:31:40 +0000, Richard Heathfield wrote:

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


    Try the MISRA-C coding guidelines.
    --
    \/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\
    \/\/\/\/\ Chris Hills Staffs England /\/\/\/\/
    \/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/
     
    Chris H, Aug 26, 2009
    #12
  13. arnuld <> wrote:
    > 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
    --
    \ Jens Thoms Toerring ___
    \__________________________ http://toerring.de
     
    Jens Thoms Toerring, Aug 26, 2009
    #13
  14. arnuld

    Flash Gordon Guest

    Nick Keighley wrote:
    > On 26 Aug, 13:12, Walter Banks <> wrote:
    >> arnuld wrote:
    >>> 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.

    >
    > 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!
    --
    Flash Gordon
     
    Flash Gordon, Aug 27, 2009
    #14
  15. On 26 Aug, 21:53, (Jens Thoms Toerring) wrote:
    > arnuld <> wrote:


    <snip>

    > [...] 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"
     
    Nick Keighley, Aug 27, 2009
    #15
  16. arnuld

    0m Guest

    On Aug 27, 10:30 am, Jack Klein <> wrote:
    > On Wed, 26 Aug 2009 17:28:02 +0100, Chris H <> wrote
    > in comp.lang.c:


    > > In message <>, arnuld
    > > <> writes
    > > >> On Wed, 26 Aug 2009 07:31:40 +0000, Richard Heathfield wrote:

    >
    > > >> 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,


    > > >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.


    > 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
     
    0m, Aug 27, 2009
    #16
  17. arnuld

    bartc Guest

    "Nick Keighley" <> wrote in message
    news:...
    > On 26 Aug, 21:53, (Jens Thoms Toerring) wrote:


    >> 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.


    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.

    --
    Bart
     
    bartc, Aug 27, 2009
    #17
  18. arnuld

    Tech07 Guest

    Richard Heathfield wrote:
    > Keith Thompson said:
    >
    > <snip>
    >
    >> 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.

    >
    > 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, Aug 30, 2009
    #18
  19. arnuld

    Tech07 Guest

    Nick Keighley wrote:
    >> 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.


    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.
     
    Tech07, Aug 30, 2009
    #19
  20. arnuld

    Jorgen Grahn Guest

    On Thu, 27 Aug 2009 09:17:03 GMT, bartc <> wrote:
    > "Nick Keighley" <> wrote in message
    > news:...
    >> On 26 Aug, 21:53, (Jens Thoms Toerring) wrote:

    >
    >>> 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.


    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

    --
    // Jorgen Grahn <grahn@ Oo o. . .
    \X/ snipabacken.se> O o .
     
    Jorgen Grahn, Aug 30, 2009
    #20
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Francisco Camarero

    VHDL Coding Guidelines

    Francisco Camarero, Jul 8, 2003, in forum: VHDL
    Replies:
    1
    Views:
    2,098
  2. Roger

    Portable Coding Guidelines?

    Roger, Dec 17, 2004, in forum: VHDL
    Replies:
    0
    Views:
    558
    Roger
    Dec 17, 2004
  3. Replies:
    2
    Views:
    512
    Lasse Reichstein Nielsen
    May 22, 2005
  4. Otto Wyss
    Replies:
    0
    Views:
    375
    Otto Wyss
    Jun 8, 2004
  5. Stuart Gerchick
    Replies:
    27
    Views:
    1,934
    Steven T. Hatton
    Nov 12, 2004
Loading...

Share This Page