Difference between revisions of "Code style guidelines"

From Minetest Developer Wiki
Jump to navigation Jump to search
Line 19: Line 19:
 
* Separate functions by two newlines (not necessary, but encouraged).
 
* Separate functions by two newlines (not necessary, but encouraged).
 
=== Do not be too C++y ===
 
=== Do 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.
+
* Avoid operator overloading like the plague.
* Avoid iterators like the plague.
+
* Don't use iterators when unnecessary.
 
* Avoid templates unless they are very convenient.
 
* Avoid templates unless they are very convenient.
 +
* Usage of macros is not discouraged at all, [http://cgit.freedesktop.org/xorg/xserver/tree/randr/rrscreen.c#n325 just don't overdo it like X.org].
 
=== 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.
Line 38: Line 39:
 
  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, and no, Boost will not even be considered, so forget it. ===
 
=== 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.
Line 44: Line 45:
 
* Don't let files get too large (over 1500 lines of code).
 
* 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.
 +
=== Miscellaneous ===
 +
* Set pointer values to NULL, not 0.  Contrary to what some people may believe, NULL is a part of the official C++ standard.
 +
* Use of Hungarian notation is very limited, to g_ for globals (rare in the first place) and m_ for members.  The former is discouraged for newer code (since one can simply notice there is no variable by that name declared in that method's scope), but needed when adding a member to older code for consistency.
 +
* Don't use distracting and unnecessary amounts of object orientated abstraction.  See [https://github.com/MovingBlocks/Terasology Terasology] and [https://github.com/prestidigitator/minetest/blob/objnoise/src/noise.cpp a certain enterprisey Java coder's conception of noise.cpp] as examples of what *not* to do.

Revision as of 05:22, 4 April 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).

Do 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).
  • Avoid operator overloading like the plague.
  • Don't use iterators when unnecessary.
  • Avoid templates unless they are very convenient.
  • Usage of macros is not discouraged at all, just don't overdo it like X.org.

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, and no, Boost will not even be considered, so forget it.

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.

Miscellaneous

  • Set pointer values to NULL, not 0. Contrary to what some people may believe, NULL is a part of the official C++ standard.
  • Use of Hungarian notation is very limited, to g_ for globals (rare in the first place) and m_ for members. The former is discouraged for newer code (since one can simply notice there is no variable by that name declared in that method's scope), but needed when adding a member to older code for consistency.
  • Don't use distracting and unnecessary amounts of object orientated abstraction. See Terasology and a certain enterprisey Java coder's conception of noise.cpp as examples of what *not* to do.