Coding Style

This is our preferred coding style. It was inspired by Google's coding style at http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml, but this set is only a small subset of it. Currently, not all our sources are following this style, and we welcome any patches to improve this.

Most of the sources follow this coding style, and the rest is being re-styled as we continue development.

Contents

File names and directories

Including files

Layout

int main()
{
    return 0;
}

Exceptions to this are one line functions in header files:

 float getValue() const { return m_my_value; }
   NetworkMode  getMode() const                   { return m_mode;            }
   void         becomeServer();
   void         becomeClient();
   void         setState(NetworkState s)          { m_state = s;              }
   NetworkState getState() const                  { return m_state;           }
   int          getMyHostId() const               { return m_host_id;         }
   void         setHostId(int host_id)            { m_host_id = host_id;      }
   unsigned int getNumClients() const             { return m_num_clients;     }
   const std::string& getClientName(int i) const  { return m_client_names[i]; }
   bool         initialiseConnections();
   void         update(float dt);

Doxygen

Use Doxygen comments. The comments for variables should be just before their declaration, and functions should be documented where they are implemented, and not where they are defined. I.e. don't document functions in the header file if they are implemented in the corresponding cpp file. Reason for this is that this way the documentation is on the screen when you debug. If you want to study the interface of a class, just look at the doxygen documentation, and all information is on one screen. But if you debug you want to know what a function is doing, then having to look at the header file is annoying. It's also easier to keep implementation details and comments in sync.

The following format should be used (Doxyfile is set up to use the first sentence as a brief description).

/** This function is called when the AI is trying to hit an item that is 
 *  pre-selected to be collected. The AI only evaluates if it's still
 *  feasible/useful to try to collect this item, or abandon it (and then 
 *  look for a new item). At item is unselected if the kart has passed it 
 *  (so collecting it would require the kart to reverse).
 *  \pre m_item_to_collect is defined
 *  \param kart_aim_angle The angle towards the current aim_point.
 *  \param aim_point The current aim_point.
 *  \param last_node
 *  \return True if th AI should still aim for the pre-selected item.
 */
bool SkiddingAI::handleSelectedItem(float kart_aim_angle, Vec3 *aim_point)
{
}   // handleSelectedItem

Feel free to use more commands like \pre, \param, \return from doxygen.

Coding

Portability

Here are a few hints about keeping Super TuxKart portable. Please consider those items when adding new source code, or cleaning up existing source code. The goal is to compile STK on as many platforms as possible, and remove all the warnings we can.

#ifdef __APPLE__
#  include <OpenGL/gl.h>
#else
#  include <GL/gl.h>
#endif

Logging

We have a separate class to Log messages for the user. This class should be used for any message that's printed on the terminal (or might be redirected into a file so that users can give us this data). Normal printf/cout/cerr are still used in many files, but this is deprecated. The various levels should be used as follows:

Retrieved from "http://supertuxkart.sourceforge.net/Coding_Style"

User Tools