    Coding Convention for Planeshift

1. Introduction
    Every programmer has his own coding style, however when multiple programmers are
    working on the same project it's a good idea to use a common coding style.
    Before starting with planeshift style. Like most of other coding standard
    documents I present some links to other docs at the end.
 

2. The Planeshift style

  a) Indentation:

    -4 chars are used for indentation
    -Tab characters are forbidden!

    -brackets are used in the following format:

    if (foo == bar)
    {
        bar++;
    }

    -lines are no longer than 78 chars unless it makes sense to keep them long
     If you have to break a line in a strange place to get it in 78 characters
     then leave it as a long line.
  
  b) Comments:
    -1 line comments are //

    -multiline comments are  /* */ 
    
    -each file should start with the following header to make licensing clear:
    (things in [] brackets are optional)

/*
 * Filename
 *
 * Copyright (C) 2001 PlaneShift Team (info@planeshift.it,
 * http://www.planeshift.it) [ - author Matze Braun <MatzeBraun@gmx.de> ]
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation (version 2 of the License)
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 *
 * [short description what is inside the file]
 */

  -some people want to separate functions in cpp files, use the following line
  for it:

//---------------------------------------------------------------------------

  -We use doxygen (http://www.stack.nl/~dimitri/doxygen/ ) for documenting
  classes and functions, so inside the header files you should use /// and /**
  before commenting classes/functions. (doxygen has more feature you can use
  of course, read the documentation on doxygen page for it). See this wiki
  page for examples:
  
  http://planeshift.sourceforge.net/wiki/index.php/PSDoxygenGuide
    
  
  c) Naming style

  - classes very tailored to the Planeshift game (not the generic engine)
    should start with a "ps" in from of their name and should use
    uppercase for each new word in them, e.g. psMyClass
  
    An exception are classes/functions that are only used internally in a .cpp
    file. For datatypes it depends, if they are big structs you should use the
    "ps"Name style.

  - Classes that deal with the gui should start with 'paws'
  
  - functions should have a capital letter at the beginning of each word, e.g.
    MyFunction

  - variables start with lowercases, e.g. 
    int myVariable;
    psEngine* psengine;

  - To explicitely mention it: We don't use hungarian name convention.

  - underscores should only be used for constants
  
  - constants and enums use ONLY capital letters, e.g. CONSTANT, PLAYER_COUNT

  - you should normally put 1 class in 1 file and name the file like the class
    in it. Ee use ONLY lower case letters (and underscores) for filenames and
    extensions are .cpp, .h and .inc, e.g.
    psmyclass.h psmyclass.cpp initcs.inc

  - Multiple classes in one source file are acceptable if the 2ndary classes
    are essentially private to the main class in the file or the data seems like
    it belongs together.

  d) Code in #defines is prohibited if that code is doing meaningful work.
     Things like declaring standard factory classes or logging error message
     expansion are fine.  Doing things with if statements and multiple C
     statements in them is not fine.

  e) Classes which have any form of persistence (db, file, network) should
     in general be responsible for marshaling their own members.  


3. Using cvs early and often

   - For those of you with write access, if you are not committing code to
     cvs at least every day or so (on the days you work on PS), you are
     probably defining your task too broadly.  Don't interpret your task
     as "Implement new GUI system for Spells" but as "Make button which
     displays icon", "Make Spellbook Parent window", etc.

   - After completing each step, re-update your cvs to merge everyone else's
     changes into yours, rebuild, make sure there are no problems and commit
     your step with a note in the history about the step and what the next
     steps are until you are finished your task.  If something is partially
     completed and will not work right if someone tries it, don't let that
     stop you from committing the part that does work.  Just note in history.txt
     what NOT to try.


4. Implementing coding style in Vim

   Here are some tips to automate some things from the coding style above:

  a) unix with vim
  - make 2 template files with the general header in them
  - Setup your vimrc to automate indentation (this is only a part of my vim
    configuration that covers indentation and syntax highlighting)

set nocompatible  
autocmd FileType cpp	call PSStyle()
autocmd FileType h	call PSStyle()
autocmd FileType inc	call PSStyle()
  
function PSStyle()
    set cindent
    set shiftwidth=4
    set tabstop=8
    set softtabstop=4
    set textwith=78
    so ${VIMRUNTIME}/syntax/syntax.vim
endfunction

filetype on




5 Some other coding styles:

    http://pcroot.cern.ch/TaligentDocs/TaligentOnline/DocumentRoot/1.0/Docs/books/WM/WM_3.html
        This is a complicated document, while some general advises are good, the
        naming convention are just another braindamaged thing like the old
        hungarian name conventions...

    http://www.gnu.org/prep/standards_toc.html
        This also covers more than indentation and naming. I personally like the
        this style as it's succesfull used in LOTS of projects howevere the
        authors don't like c++ :(, and the document enforces you a bit too lot I
        think (style for a changelog?!?)

    http://developer.gnome.org/doc/guides/programming-guidelines/book1.html
        Some more general advices and nearly some indentation/naming style as
        gnu uses

    http://purists.org/linux/
        To present something different to gnu, here's linus view of coding style
        , also a good read, you should especially look at the "functions" and
        "commenting" sections.

    http://crystal.sourceforge.net/docs/online/manual/cs_263.html#SEC619
        The style of Crystal Space our 3d engine. We're using their naming
        conventions as it's the only way not to end up with 2 naming styles in
        our application. Howevere we use another indentation style and change
        some other things.

    Compared with all these docs the planeshift coding convention is poor and lets
    you much room, if you have more questions/additions feel free to contact the
    mailing list:
    
    planeshift-engine@lists.sourceforge.net

