Code style guidelines

From Minetest Developer Wiki
Jump to navigation Jump to search

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

Sometimes with complex function declarations it might be messy to define as many parameters as possible on the same line. This is acceptable too (and currently used in some places):

void some_function_name(
	const ReallyBigLongTypeName &param1,
	ReallyBigLongTypeName *param2,
	void *param3,
	size_t param4,
	const void *param5,
	size_t param6)
{
	...
}

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 pass non-const references to functions.
  • Don't use initializer lists unless absolutely necessary (initializing an object inside a class, or initializing a reference).
  • Try to minimize the usage of exceptions.
  • 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. (note: this column count assumes 4-space indents)
  • 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, ...) are in the slow process of being cleaned up.

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. Scope specifiers such as g_ for globals, s_ for statics, or m_ for members are allowed. The prefix m_ is discouraged for public members in newer code as it is a part of the class' interface, but sometimes needed for consistency when adding a member to older code.
  • Don't use camelCase for local variables. Use lowercase_and_underscored instead.
  • Don't use distracting and unnecessary amounts of object orientated abstraction. See Terasology as an example of what not to do.
  • As an annendum to the last point, don't randomly add unnecessary design patterns to your code, such as factories/providers/sources