Coding style - PHLF/TA3D GitHub Wiki

GENERAL

• Do not use Java coding style GOOD :

  if ()
  {
    // Do something
  }

BAD :

  if () {
    // Do something
  }

• Use UTF-8 in all files

• Use spaces instead of tabs (we commonly use 4 whitespaces for 1 tab) NB: the code should be designed to be look the same on most editors accross all supported platforms

• Do not use semicolon for namespaces, nor switch statements

• Extensions for files :

  • header .h
  • source code .cpp
  • source code for template .hxx
  • Text files .txt

• Always leave at one space before and after operators GOOD

  if (a == 10 && b == 42)
  {}

BAD

  if (a==10&&b==42)

GOOD

  for (int i = 0; i < 10; ++i)

BAD

  for(int i=0;i<10;++i)

• Avoid magic numbers BAD

  if (42 == foo)
     startThermoNuclearWar();

GOOD

  if (YUNI_I_CAN_PUSH_ON_THE_RED_BUTTON == foo)
     startThermoNuclearWar();

• Use the keyword NULL instead of 0 for pointers

NAMING CONVENTION

• namespaces (camel case + begins with an upper case) (except for TA3D which should be written TA3D and not Ta3d) GOOD :

  namespace HereIsANewNamespace {}

• Classes (camel case) : GOOD :

  class IAmAClass
  {};

BAD :

  class iAmClass
  {};
  class I_am_class
  {};

• methods (camel case + begins with a lower case) method parameters (camel case + begins with a lower case) GOOD :

  void myMethod(void myVeryLongParameter);

• private/protected variables. Attributes should be separated only by one space from their type. Private attributes should start with p then use camel case. GOOD :

  int pPrivateAttribute;
  float pAccount;

BAD :

  int       pTest;
  int PTest;

In case of a long list, they should be aligned. GOOD :

  int    pPrivateAttribute;
  float  pAccount;
  byte   smallByte;
  String name;

BAD :

  int pPrivateAttribute;
  float pAccount;
  byte smallByte;
  String name;

• Always prefer a variable name that describes what the variable is used for GOOD

  if (hours < 24 && minutes < 60 && seconds < 60)

BAD

  if (a < 24 && b < 60 && c < 60)

• Macros and defines are all in uppercase All Macros that define an exported header of yuni must have the prefix YUNI_

• The symbol to indicate a pointer or a reference must be sticked to the name because it describes the way you access the data GOOD

  void foo(const String &s);

BAD

  void foo(const String& s);

COMMENTS

• Use C++ Doyxgen style GOOD :

  /*!
  ** \brief Some brief description here
  ** \param paramName Description
  */

BAD :

  /*!
  ** @brief
  */
  /**
  ** \brief
  */

• One liners may use the C++ style comments (omitting the \brief keyword) :

  //! Some description here

• Use the in/out keyword for doxygen if needed :

  /*!
  ** \brief An useless routine
  ** \param a The first value
  ** \param b The second value
  ** \param [out] ret The result of the addition of `a` and `b`
  */
  void uselessMethod(const int a, const int b, int& ret)
  {
      ret = a + b;
  }

BEST PRACTICES

• Prefer this test (for strings) :

      if (!s.empty())

to

      if (s != "")

• Prefer this form :

      ++i

to

      i++

(Note: It does not change anything for builtin types)

• Use and abuse LOG_ASSERT tests.

• Prefer this form (assuming int i;):

    if (42 == i)

to

    if (i == 42)

• Don't put an else right after a return. Delete the else, it's unnecessary and increases indent level. BAD :

  if (...)
     return;
  else
     return;

• Avoid as much as possible pointers. Prefer references. A Pointer indicates that we should expect to get a NULL value and in this case the NULL value has a meaning

• Avoid as much as possible const char* or char*. Use Yuni::String instead for strings.

• Avoid as much as possible all constructors by copy

• Header file guards : their name should follow the directory structure

• If your class is copyable, define both a copy constructor and an assignment operator

• Be Const Correct : Use and abuse the const keyword from the start. It is a nightmare to add it in later.

• Don't place "using namespace" directives in headers

• Prefer inlines to macros. In C++ macros are not needed for code efficiency

• The system headers should be included before any other include

• Avoid as much as possible Copy constructor for Return Values. Use reference instead.

• Compile time is without incidence. Increasing compile time to reduce execution time (e.g. with templates) is encouraged.