Difference between revisions of "Code style guidelines"

From Minetest Developer Wiki
Jump to navigation Jump to search
Line 1: Line 1:
=== General Guidelines ===
+
For everybody else's sanity, please just use something that resembles the [https://www.kernel.org/doc/Documentation/CodingStyle Linux Kernel code style], with the exception that cases in switch statements are indented a level. Much of the already existing code is somewhat weird looking and breaks the current code guidelines, do not try to replicate that. Use your best judgement for C++-specific syntax.
For everybody elses' sanity, please just use something that resembles [https://www.kernel.org/doc/Documentation/CodingStyle the Linux Kernel code style], with the exception that cases in switch statements are indented a level. Much of the already existing code is somewhat weird looking and breaks the current code guidelines, do not try to replicate that. Use your best judgement for C++-specific syntax.
 
 
=== Spaces ===
 
=== Spaces ===
* Do NOT use spaces for indentation
+
* Do '''not''' use spaces for indentation.
* Try to stay under 6 levels of indentation
+
* Try to stay under 6 levels of indentation.
* Do add spaces between operators so they line up when appropriate (don't go overboard). For example:
+
* Do add spaces between operators so they line up when appropriate (don't go overboard). For example:
 
  np_terrain_base  = settings->getNoiseParams("mgv6_np_terrain_base");
 
  np_terrain_base  = settings->getNoiseParams("mgv6_np_terrain_base");
 
  np_terrain_higher = settings->getNoiseParams("mgv6_np_terrain_higher");
 
  np_terrain_higher = settings->getNoiseParams("mgv6_np_terrain_higher");
Line 15: Line 14:
 
  np_beach        && np_biome          && np_cave;
 
  np_beach        && np_biome          && np_cave;
 
The above code looks really nice.
 
The above code looks really nice.
* Separate different parts of functions with newlines for readability
+
* Separate different parts of functions with newlines for readability.
* Separate functions by two newlines (not necessary, but encouraged)
+
* Separate functions by two newlines (not necessary, but encouraged).
=== Don't be too C++y ===
+
=== Don not be too C++y ===
* Don't use references when they're not necessary. They are rather inflexible and can be misleading.
+
* Don't use references when they're not necessary. They are rather inflexible and can be misleading.
* Don't use initializer lists unless absolutely necessary (initializing an object inside a class, or initializing a reference)
+
* Don't use initializer lists unless absolutely necessary (initializing an object inside a class, or initializing a reference).
* Try to avoid operator overloading
+
* Try to avoid operator overloading.
* Avoid iterators like the plague
+
* Avoid iterators like the plague.
* Avoid templates unless very convenient
+
* Avoid templates unless they are very convenient.
 
=== Classes ===
 
=== Classes ===
* Don't put actual code in header files, unless it's a 3-liner or an inline function
+
* Don't put actual code in header files, unless it's a 3-liner or an inline function.
* Class definitions should go in header files
+
* Class definitions should go in header files.
* Substantial (over 4 LoC) methods are defined outside of the class definition
+
* Substantial (over 4 lines) methods are defined outside of the class definition.
* Class names are PascalCase, method names are camelCase
+
* Class names are PascalCase, method names are camelCase.
* Functions not part of any class should be unix_lowercase_underscore_style()
+
* Functions not part of any class should be <code>unix_lowercase_underscore_style()</code>.
 
=== Comments ===
 
=== Comments ===
 
* Don't make uninformative comments like this:
 
* Don't make uninformative comments like this:
Line 36: Line 35:
 
   
 
   
 
  draw_load_screen(L"Loading...", driver, font);
 
  draw_load_screen(L"Loading...", driver, font);
* Add comments to explain a non-trivial but important detail about the code, or explain behavior that is not obvious
+
* Add comments to explain a non-trivial but important detail about the code, or explain behavior that is not obvious.
 
=== Use STL, avoid Irrlicht containers ===
 
=== Use STL, avoid Irrlicht containers ===
 
=== Don't let things get too large ===
 
=== Don't let things get too large ===
* Try to keep lines under 80 characters. It's okay if it goes over by a few, but 90 character lines or larger are definitely unacceptable.
+
* Try to keep lines under 80 characters. It's okay if it goes over by a few, but 90 character lines or larger are definitely unacceptable.
* Functions should not be over 200 LoC - if you are concerned with having to pass too many parameters to child functions, make whatever it is into a class
+
* Functions should not have over 200 lines of code - if you are concerned with having to pass too many parameters to child functions, make whatever it is into a class.
* Don't let files get too large (over 1500 LoC)
+
* Don't let files get too large (over 1500 lines of code).
* Currently existing huge files (game.cpp, server.cpp, etc.) are in the slow process of being cleaned up
+
* Currently existing huge files (game.cpp, server.cpp, etc.) are in the slow process of being cleaned up.

Revision as of 20:26, 10 March 2013

For everybody else's sanity, please just use something that resembles the Linux Kernel code style, with the exception that cases in switch statements are indented a level. Much of the already existing code is somewhat weird looking and breaks the current code guidelines, do not try to replicate that. Use your best judgement for C++-specific syntax.

Spaces

  • Do not use spaces for indentation.
  • Try to stay under 6 levels of indentation.
  • Do add spaces between operators so they line up when appropriate (don't go overboard). For example:
np_terrain_base   = settings->getNoiseParams("mgv6_np_terrain_base");
np_terrain_higher = settings->getNoiseParams("mgv6_np_terrain_higher");
np_steepness      = settings->getNoiseParams("mgv6_np_steepness");
np_height_select  = settings->getNoiseParams("mgv6_np_height_select");
...
bool success =
	np_terrain_base  && np_terrain_higher && np_steepness &&
	np_height_select && np_trees          && np_mud       &&
	np_beach         && np_biome          && np_cave;

The above code looks really nice.

  • Separate different parts of functions with newlines for readability.
  • Separate functions by two newlines (not necessary, but encouraged).

Don not be too C++y

  • Don't use references when they're not necessary. They are rather inflexible and can be misleading.
  • Don't use initializer lists unless absolutely necessary (initializing an object inside a class, or initializing a reference).
  • Try to avoid operator overloading.
  • Avoid iterators like the plague.
  • Avoid templates unless they are very convenient.

Classes

  • Don't put actual code in header files, unless it's a 3-liner or an inline function.
  • Class definitions should go in header files.
  • Substantial (over 4 lines) methods are defined outside of the class definition.
  • Class names are PascalCase, method names are camelCase.
  • Functions not part of any class should be unix_lowercase_underscore_style().

Comments

  • Don't make uninformative comments like this:
/*
	Draw "Loading" screen
*/

draw_load_screen(L"Loading...", driver, font);
  • Add comments to explain a non-trivial but important detail about the code, or explain behavior that is not obvious.

Use STL, avoid Irrlicht containers

Don't let things get too large

  • Try to keep lines under 80 characters. It's okay if it goes over by a few, but 90 character lines or larger are definitely unacceptable.
  • Functions should not have over 200 lines of code - if you are concerned with having to pass too many parameters to child functions, make whatever it is into a class.
  • Don't let files get too large (over 1500 lines of code).
  • Currently existing huge files (game.cpp, server.cpp, etc.) are in the slow process of being cleaned up.