Coding Style

From Platinum Arts Sandbox Free 3D Game Maker
Jump to: navigation, search

Patches

Patches should be sent using the unified style. These can typically generated through diff -u, svn diff uses this format by default. These patches contain some context information which makes them much easier to apply should there be intermediary changes and generally they are human readable.

Source Code

These are just rough guidelines, when it doubt mimic the style of the surrounding code.

When not writing one liners, braces should be placed on their own lines with the programming statements following on a new line. Braces are to maintain the current level of indentation. Should you write a if, else or while statement that only does one thing, braces are optional.

Good

   int myfunc() { return 4; }
   
   if(conditon) { function(); variable++; }
   else         { function2(); var2++; }
   
   int myfunc()
   {
       return 4;
   }
   
   if(condition)
   {
       function();
       variable++;
   }
   else
   {
       function();
       variable++;
   }

Bad

   int myfunc() {
       return 4
   }
   
   int myfunc()
   {   int a = 4;
       return a;
   }
   
   int myfunc()
       {
           return 4
       }
   
   int myfunc()
   {
       if (cond)
           {
               return 4;
           }
       else
           {
               return 2;
           }
   }
   
   if(condition) {
       stuff()
   } else {
       dostuff();
   }

Indentation wise, you will be using either 4 spaces or tabulators. Which depends on the file you modify so keep an eye out. As a general rule the engine stuff and the FPS game uses 4 spaces whilst everything else uses tabs. Tab size should be irrelevant but the best experience should be with a size of 4.

There aren't many fixed rules and you are allowed some freedom provided they make things more readable, with that said you are encouraged to indent liberally rather than conservatively.

Good

   switch(var)
   {
       case 1:
           #ifdef A
           break;
           #endif
       case 2:
       case 3:
       default:
           break;
   }
   
   class A
   {
       public:
           void stuff() {}
   }

Discouraged

   {
       switch(var)
       {
       case 1:
   #ifdef A
           break;
   #endif
       case 2:
       case 3:
       default:
           break;
       }
   }
   
   class A
   {
   public:
       void stuff() {}
   }

Subjective

   glBegin(GL_TRIANGLE_STRIP);
       glVertex2i(sx, sy);
       glVertex2i(ex, sy);
       glVertex2i(sx, ey);
       glVertex2i(ex, ey);
   glEnd();


When defining prototypes and variable names, place any special qualifiers (such as * or &) next to the variable name as opposed to the type. This is done mainly due to C/C++ parsing rules and the interest of readability. This also goes for prototypes and their argument lists.

Good

   const char *A, *B;
   const char *strstr(const char *haystack, const char *needle);

Bad

   const char* A, B; //note the types are const char*, and const char respectively
   const char* strstr(const char* haystack, const char* needle);


Variable and function names should be short, succinct and to the point. We should be able to infer from the name alone what the variable's purpose is. Where possible, use common, accepted names for variables and descriptive verbs for functions. For example i, j, k or n are excellent variable names when you're counting or checking against some sort of index, and verbs like "destroy" are ideal for functions that are intended to remove something from the game. When it comes to writing the names, the rules as as follows

  • Hungarian notation is not allowed, use int num over int iNum
  • CamelCase is discouraged, but is accepted. Note that ThisIsPreferred and that thisIsNotPreferred.
  • constants should always be written in ALL CAPS. macros are also preferred this way but this is not a strict requirement

Good

   int i, j, count;
   
   enum
   {
       FIRST = 0,
       SECOND,
       THIRD
   };

Bad

   int iCount;
   bool bMerge;
   
   enum
   {
       First = 0,
       Second,
       Third
   };


When defining prototypes, especially when doing it as an extern or the like, name all the arguments. C/C++ does allow you to only specify the types, but we will not permit such code. You are welcome to specify defaults where they make sense.

Good

   void function(int a, int b, float &ref, const char *ptr = NULL);

A crime against humanity

   void function(int, int, float&, const char*);


Comment wise, we believe in writing clean, simple, self documenting code. This obviously isn't always possible and there may be strange quirks, odd preconditions or convoluted logic and it is these cases you must comment. As a rule of thumb if you write something and there's a chance that you or someone else might trip up if you make further modifications try to use it or simply understand it, make a comment.

Cubescript