gcl-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Gcl-devel] Re: Proposed GCL Coding Guidelines...


From: Camm Maguire
Subject: [Gcl-devel] Re: Proposed GCL Coding Guidelines...
Date: 13 Jan 2002 11:55:01 -0500

Greetings!  Thanks Robert so much for suggesting this.  I thought I'd
post to the list for any discussion.  We also need to keep in mind the
GNU Coding Standards, as we are an official part of GNU.  I'll try to
post that document too soon for our consultation.

Take care,


Robert Alan Byer <address@hidden> writes:

> -----BEGIN PGP SIGNED MESSAGE-----
> 
> 
> Here is what I propose for now as GCL coding guidelines to help get things 
> organized and get everyone on the same page a bit.  They were adopted from 
> the FreeCIV project and I think they will help out alot here.
> 
> (yes, they are a little picky, but I think it will save some headaches in 
> the long run)
> 
> Look it over and tell me what you think.  If they are OK I think it would 
> be good to place it in CVS for future reference and so others that join can 
> easily find them.
> 
> 
> ===========================================================================
>  Proposed GCL Style Guide
> ===========================================================================
> 
> If you want to work on GCL, and want your patches to be accepted, it
> helps to follow some simple style rules. Yes, some of these are a bit 
> nit-picky, but wars are fought over the silliest things...
> 
> - - Use K&R indentation style with indentation 2 (if in doubt, use
>   "indent -kr -i2").  However, do not re-indent areas of code you are
>   not modifying or creating.
> 
> - - Set lines to 80 columns. Lines should not wrap, ever.
> 
> - - An empty line should be placed between two separate blocks of code.
> 
> - - Spaces should go before and after operators, and after commas:
> 
> int a,b,c;   /* bad */
> int i, j, k; /* good */
> 
> if(foo<=bar) {   /* all bad */
>   c=a+b;
> }
> 
> if(foo <= bar) { /* good */
>   c = a + b;
> }
> 
> ================================
>  Comments
> ================================
> 
> - - Don't use C++-style comments (i.e., // comments).
> 
> - - Every function should have a comment header. It should be above the 
>   function's implementation, not the prototype:
> 
> /*************************************************************************
>  the description of the function should be here
>  any information is helpful, such as who calls this function, etc.
>  do _not_ introduce a new function without some sort of comment.
> *************************************************************************/
> int the_function_starts_here(int value) 
> {
>   ...
> }
> 
> - - Comments which take more than one line. Asterisks should be placed in
>   front of the comment line like so:
> 
>   /* I am a comment
>    * blah blah 
>    * blah blah */
> 
> - - Comments in declarations. If you need to comment a declared variable,
>   it should be as such:
> 
>   struct foo {
>     int bar;                    /* bar is used for ....
>                                  * in ..... way */
>     int blah;                   /* blah is used for .... */
>   };
> 
> - - Comments in conditionals. If you need a comment to show program flow,
>   it should be below the if or else:
> 
>   if(is_barbarian(pplayer)) {
>     x++;
>   } else {
>     /* If not barbarian, ... */
>     x--;
>   }
> 
> 
> ================================
>  Declaring variables
> ================================
> 
> - - Variables can be initialized as soon as they're declared:
> 
> int foo(struct unit *punit)
> {
>   int x = punit->x;
>   int foo = x;
>   char *blah;
> 
>   ...
> }
> 
> - - After variables are declared, there should be an empty line before the
>   rest of the function body.
> 
> - - Merging declarations. Variables do not have to be declared one per line;
>   however, they should only be grouped by similar function.
> 
> int foo(struct city *pcity)
> {
>   int i, j, k;
>   int total, cost;
>   int build = pcity->shield_stock;
> }
> 
> ================================
>  Bracing
> ================================
> 
> - - Function braces should begin and end in the first column:
> 
> int foo()
> {
>   return 0;
> }
> 
>  and not:
> 
> int foo() {
>   return 0;
> }
> 
> - - Extra braces on iterates. Note that the *_iterate_end; should be placed 
>   on the same line as the end brace:
> 
>   unit_list_iterate(pcity->units_supported, punit) {
>     kill(punit);
>   } unit_list_iterate_end;
> 
> - - In switch statements, braces should only be placed where needed, i.e. to
>   protect local variables.
> 
> - - In general, [unnecessary] braces should be applied after conditionals:
> 
>   if(x == 3) {
>     return;
>   }
> 
>  and 
> 
>   if(x == 3) {
>     return 1;
>   } else {
>     return 0;
>   }
> 
> ================================
>  Other stuff
> ================================
> 
> - - If an empty block is needed you should put an explanatory comment in
>   an empty block (i.e. {}):
> 
>   while(*i++) {
>     /* nothing */
>   }
> 
> - - Order include files consistently:  First state all system include
>   files with <> in alphabetic order, then all GCL include files
>   with "", sorted by directory (common, server, ...) and then by
>   alphabetic order, with a blank line between the sections.  This helps
>   to avoid adding unnecessary or duplicated include files.
> 
> - - If you use a system specific feature, don't add #ifdef __CRAY__ or
>   something like that.  Rather write a check for that feature for
>   configure.in, and use a meaningful macro name in the source.
> 
> - - Always prototype global functions in the appropriate header file.
>   Local functions should always be declared as static and prototyped
>   at the top of the file.  Use "-Wmissing-prototypes -Wmissing-declarations"
>   to catch these.
> 
> - - If you send patches, use "diff -u" (or "diff -r -u").  Also,
>   name patch files descriptively (e.g. "fix-foo-bug-0.diff" is good,
>   but "gcl.diff" is not).
> 
> - - When doing a "diff" for a patch, be sure to exclude unnecessary files
>   by using the "-X" argument to "diff".
> 
> ===========================================================================
> 
> 
>  +------------------+--------------------------+---------------+
>  | Robert Alan Byer | address@hidden | ICQ #65926579 |
>  +------------------+--------------------------+---------------+
>  | Send an E-mail request to obtain a copy of my PGP key.      |
>  +-------------------------------------------------------------+
>  | "It is by caffeine alone I set my mind in motion.  It is by |
>  |  cans of cola the thoughts aquire speed, the hands acquire  |
>  |  shakes, the shakes become a warning.  It is by caffeine    |
>  |  alone I set my mind in motion."                            |
>  +-------------------------------------------------------------+
> 
> 
> -----BEGIN PGP SIGNATURE-----
> Version: 2.6.3ia
> Charset: noconv
> 
> iQEVAwUBPD9oKKVSqzlBVJbBAQHMiwgArBurluWUSGvzbF8SCzHNHv80ydQcMkJE
> wId4WcM5HoHg8POeqSS/7jkKFzNWo3zvVfPx+wQr4wWguOTds5gJiNjCKfNx+QO9
> Ud5AesJSRG0A71EBZDElUtqmSsIK/qmhkOoQkeW1RO+zeB7wfCgq9Gy++4bzNjvT
> nZZTiRs4qrlfqvP5nttoRJ8BYNK09kjR9ahktgRSXgg9qwXlL56y7gC+6tmxWuMb
> ykeUVHlFEARs5VPbbtT4mj1mYWDD8XC3ESRrCw9B5F0tewTgOKUyNbvBolLf71wP
> 4BWEhwDkXaopUBljeQR2omPuVWaKQqfBLtrEXdTv0p7HRBLOgXgmgA==
> =AS5y
> -----END PGP SIGNATURE-----
> 
> 

-- 
Camm Maguire                                            address@hidden
==========================================================================
"The earth is but one country, and mankind its citizens."  --  Baha'u'llah



reply via email to

[Prev in Thread] Current Thread [Next in Thread]