[Mapserver-dev] Coding Standards

[Daniel Morissette]

Steve Lime wrote:
> 
> Subject says it all. Depending on who wrote the code rumaging through
> the source can be kinda trying. I'm thinking we need a document that
> lays out coding standards, especially as the list of developers grows.
> For example, I like the naming convension that some folks use for
> function parameters and local variables and would like to adopt that
> myself. However, I (personally) hate if-then's or function calls that
> span multiple lines- have to scroll too much when editing. Thoughts?
> 

Hi Steve,

I agree that a common coding style would be very welcome.  I attached
below the bases of the coding style that we try to follow at DM
Solutions, it also matches what Frank uses for his libs (GDAL, OGR,
shapelib, etc.).  You'll notice that it's extremely simple, just enough
to keep the code clean without making it too complicated for new
developers to learn and follow the rules.

I'm not saying MapServer-Dev should adopt this coding style, but of
course it would be easier for us if we did.  ;)  I'm sending it to the
group as a base for discussion.

I would like to elaborate more but I'm taking off right now and will be
back only on Monday.  I'm sure others will have many ideas.  Hopefully
Frank and Assefa will defend the value of this coding style in my
absence.  ;)

Daniel

P.S. Contrary to you I have don't like if-then blocks that start at the
end of the line and I much prefer having brackets on separate lines, but
that's just a natural preference and I respect your choice.
-- 
------------------------------------------------------------
 Daniel Morissette               morissette at dmsolutions.ca
 DM Solutions Group              http://www.dmsolutions.ca/
------------------------------------------------------------


The rules that MUST be followed:
--------------------------------

1- Make our code fit in 80 columns unless it's not practical to do so
because of a long function name or an expression that would become
unreadable if broken on several lines.

2- NO TABS... set your editor to produce spaces instead of tabs...
that's because some editors use 4 chars tabs and some use 8 chars and
everything looks screwed up if you allow the use of tab chars.

#1 and #2 are also a requirement with some of our external clients like
Safe.

3- Brackets... we use this
     if (...)
     {
         ...;
     }
     else
     {
         ...;
     }

More flexible rules: (some may not apply depending on context)
--------------------

4- Indent is 4 chars usually.  We've used 2 chars in some places but we
try to stick to 4.

5- Use hungarian notation for variables (makes more sense in C than in
PHP):

 Prefix     Description
 ------     ----------------------------
   b         Boolean
   c         Char
   n         Integer value
   i         Integer, used as a counter in a loop for instance
             (we also often use the vars i, j, or k for counters)
   f         Float, single precision
   d         Double precision Float (we also use "df" sometimes)
   sz        String zero-terminated (a C string!)
   by        Byte
   o         Object
   s         Structure
   fp        FILE *

   a         Array of ...
   p         Pointer to ...
   
   k         Constant
   m         Class member variable (we also use "m_" sometimes)
   g         Global variable

 Examples:
 ---------
   char   szFilename[100];
   char   *pszFilename;
   int    nProjectId;
   int    i, j, k;
   int    iField;
   double dX, dY;
   char   **papszLines;
   TABFile *poSrcFile;
   GBool  bSuccess;


6- Function and variable names use upper-lowercase combinations instead
of underscores, e.g.  int nProjectId instead of project_id,

7- Filenames and directory names: 

    - Avoid spaces or special non-alphanumerical characters in
filenames.
      The safe characters to use in filenames are "a-z", "0-9", "_" and
"."

    - Avoid uppercases in filenames, except for special files that
should
      show up at the top of a directory listing like README.TXT, 
      INSTALL.TXT, etc.  For the rest try to stick to lowercase-only 
      filenames, that makes our lives much easier when porting code 
      between Windows and Unix.

8- Comments... quite flexible... we most of the time use something like
this for function headers:

/*****************************************************************
 *                          MyFunction()
 *
 * This function will do something pretty cool.  It expects numbers
 * as arguments and returns a pointer to a buffer newly allocated.
 *
 * The caller should free the returned buffer.  NULL is returned in
 * case of error.
 *****************************************************************/

and for comments inline, it's either a short one-line /*... */ thing, or
if it's longer then we sometimes use the following to also act as a
delimiter of an important part of a function:

/* --------------------------------------------------------------
 *  OK, this is an interesting comment...
 * -------------------------------------------------------------- */

Some people (Frank and Assefa at least) use some Emacs macros 
to automatically format these comments.