Difference between revisions of "Code Style"

(Initial code style.)
 
(Removed math guideline.)
Line 197: Line 197:
  
 
I personally prefer tabs, but I know I'm the only person in the world. We will probably end up with spaces, in which case I suggest 4 spaces per level.
 
I personally prefer tabs, but I know I'm the only person in the world. We will probably end up with spaces, in which case I suggest 4 spaces per level.
 
== Math and stuff ==
 
 
* Use spaces between operators.
 
 
'''YES:'''
 
 
a = (x + y) * z;
 
 
'''NO:'''
 
 
a=(x+y)*z
 
  
 
== Documentation blocks ==
 
== Documentation blocks ==

Revision as of 10:31, 27 June 2012

Introduction

"Every second spent enforcing code style is a waste of time". -- Someone, at some point

Status: FALSE

When I encounter really pretty code in the open-source world (and the closed-source world for that matter), I'm a lot more confident that the software has real quality. Of course, from case to case, this may actually not be true, and the style might lie to me, but the important thing is that it appears to have high quality to people. On the other hand, if I encounter code which appear to be shit (although it might really be of excellent quality), it's tempting for me to try and find some alternative. So while enforcing code style might technically be a waste of time, it's psychologically. Also, if you ever intend to use LÖVE as a reference when applying for a job (I've done that), there is a slight chance they will take a ten second look on the code. Even if they are advanced enough to evaluate the code properly, they will not be immune to good (nor bad) style.

Therefore, because I'm such a fucking drone, I'm going to refactor some code here and there (or everywhere) to make things more beautiful. And since I'm potentially fucking up everything anyway, I thought we could decide on a coding style that the majority likes. It's unlikely that we all agree on everything ... but hopefully everyone will accept the decision of the majority.

Namespaces

  • Any number of namespaces indent just one level.
 YES:
 namespace love
 {
 namespace graphics
 {
     class Foo
     {
     };
 } // graphics
 } // love
 NO:
 
 namespace love
 {
     namespace graphics
     {
         class Foo
         {
         };
     } // graphics
 } // love

Class declarations

  • Should normally have a capital first letter.
  • Visiblity blocks should be in decreasing order. It makes sense to have the visible "API" first. This is what a reader will normally want to know first anyway.
  • For multiple inheritance, each class should appear on its own line, with the ":" or "," in front of it. My experience is that this is the most flexible style with respect to diffs and #ifdeffery.
 YES:
 class Foo
 {
 public:
 protected:
 private:
 };
 NO:
 class Foo
 {
 private:
 protected:
 public:
 };
 
 YES:

 class Foo : public Bar
 {
 };
 class Foo
     : public Bar
     , public Foz
 {
 };
 NO:

 class Foo : public Bar, public Foz
 {
 };

Initializer lists

  • Like inheritance lists.
 YES:

 Foo::Foo()
     : bar(0)
     , foo(1)
 {
 }
 NO:
 Foo::Foo() : bar(0) , foo(1)
 {
 }

Functions/methods

  • Functions and methods should use camelCase.
  • One-liners like getters and setters can be inlined in the class declaration.
 YES:
 
 int doomFist(int where);
 NO:
 int DoomFist(int where);
 int doom_fist(int where);

Control blocks

  • Control blocks should have a space between the keyword the parenthesized expression. This differentiates control statements visually from function calls.
  • Braces should normally be omitted if they can. (Saves vertical space).
  • Braces should appear on the next line.
 YES:

 if (foo)
     /* ... */;
 NO:
 if(foo)
     /* ... */;
 YES:

 if (foo)
     bar();
 NO:
 if (foo)
 {
     bar();
 }
 YES:
 if (foo)
 {
     bar1();
     bar2();
 }
 NO:
 
 if (foo) {
     bar1();
     bar2();
 }

Pointer affinity

  • For pointers and references, "*"/"&" should appear next to the type. This is logical, because being a reference or pointer is a property of the type. Our current style makes everything look like multiplications to me, which is confusing.
YES:

int* foo;
int& bar;
NO:

int *foo;
int &bar;

int * foo;
int & bar;
YES:

int* get_int_ptr();
int& get_int_ref();

NO:
int *get_int_ptr();
int &get_int_ref();
int * get_int_ptr();
int & get_int_ref();

I know this breaks down if you like to declare multiple pointers in one go, like:

int *foo, *bar, *fooz;

My recommendation is that we just not do this. Alternative:

int* foo;
int* bar;
int* fooz;

Spaces vs Tabs

I personally prefer tabs, but I know I'm the only person in the world. We will probably end up with spaces, in which case I suggest 4 spaces per level.

Documentation blocks

  • Align the asterisks vertically.
YES:

 /**
  * Short description.
  *
  * @param foo The foo that goes in the bar.
  * @param bar The bar the foo foes into.
  */
 int foz(int foo, int& bar);

NO:

 /**
 * Short description.
 *
 * @param foo The foo that goes in the bar.
 * @param bar The bar the foo foes into.
 */
 int foz(int foo, int& bar);