Difference between revisions of "Code style guidelines"

From Minetest Developer Wiki
Jump to navigation Jump to search
Line 88: Line 88:
 
* <span style="color: red">Do '''not''' use "or", use "||".</span>
 
* <span style="color: red">Do '''not''' use "or", use "||".</span>
 
* Set pointer values to NULL, not 0. Contrary to what some people may believe, NULL is a part of the official C++ standard.
 
* 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 latter 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.
+
* Use of Hungarian notation is very limited, to g_ for globals (rare in the first place) and m_ for members.  The latter is discouraged for public members in newer code as it is a part of the class' interface (we don't prefix methods with m_, do we? :) ), 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.h a certain enterprisey Java coder's conception of perlin noise] as examples of what not to do.-->
 
* 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.h a certain enterprisey Java coder's conception of perlin noise] as examples of what not to do.-->

Revision as of 17:50, 8 November 2014


This is the coding style used for C/C++ code. Also see the Lua code style guidelines.

The coding style is based on the Linux kernel code style. Much of the existing code doesn't follow the current code style guidelines, do not try to replicate that. Use your best judgement for C++-specific syntax.

Function declarations

In case your function parameters don't fit within the defined line length use following style. Indention for follow up lines is exactly one tab.

void some_function_name(type1 param1, type2 param2, type3 param3,
	type4 param4, type5 param5, type6 param6, type7 param7,
	type8 param8)
{
	...
}

Spaces

  • Do not use spaces to indent.
  • 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).
  • Use a space after if, else, for, do, while, switch, case, try, catch, etc.
  • When breaking conditionals indent following lines of the conditional with two tabs and the statement body with one tab. For example:
for (std::vector<std::string>::iterator it = strings.begin();
		it != strings.end();
		++it) {
	*it = it->substr(1, 1);
}

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, just don't overdo it like X.org.

Classes

  • Class names are PascalCase, method names are camelCase.
  • 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.
  • Functions not part of any class should use lowercase_underscore_style().

Comments

  • Doxygen comments are acceptable, but please put them in the header file.
  • 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

  • In general, adding new dependencies is considered serious business.

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).

Miscellaneous

  • Do not use "or", use "||".
  • 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 latter is discouraged for public members in newer code as it is a part of the class' interface (we don't prefix methods with m_, do we? :) ), but needed when adding a member to older code for consistency.
  • Don't use distracting and unnecessary amounts of object orientated abstraction.