CodingStandards - Revision history

Vultraz: /* Idioms */

2025-03-05T16:24:44Z

‎Idioms

Celtic Minstrel: /* Avoid standard C functions */ New section

2025-01-13T14:25:56Z

‎Avoid standard C functions: New section

Celtic Minstrel: Use syntax highlighting

2025-01-13T14:20:11Z

Use syntax highlighting

Celtic Minstrel: /* Do not use sprintf */ Delete section

2025-01-13T14:13:39Z

‎Do not use sprintf: Delete section

Bssarkar: /* Evil things to avoid */

2025-01-13T06:48:34Z

‎Evil things to avoid

Bssarkar: /* C++ version */ update C++ version

2025-01-13T06:14:47Z

‎C++ version: update C++ version

Pentarctagon: /* C++ version */

2021-01-23T02:04:40Z

‎C++ version

Pentarctagon at 23:06, 28 December 2020

2020-12-28T23:06:28Z

Loonycyborg: /* C++ version */

2019-01-24T21:17:30Z

‎C++ version

Josteph: /* Formatting */

2018-08-27T11:56:30Z

‎Formatting

← Older revision		Revision as of 16:24, 5 March 2025
Line 140:		Line 140:

	For more information, you can read about the (important) RAII idiom: http://c2.com/cgi/wiki?ResourceAcquisitionIsInitialization		For more information, you can read about the (important) RAII idiom: http://c2.com/cgi/wiki?ResourceAcquisitionIsInitialization
		+
		+	=== Prefer anonymous namespaces ===
		+
		+	Translation unit-specific (i.e., local to a specific .cpp file) helper functions, types, and variables should be placed together in an anonymous namespace rather than declaring them static individually.

	== Standard C++ to avoid ==		== Standard C++ to avoid ==

@@ Line 193: / Line 193: @@
+}
 </syntaxhighlight>
 == Documentation ==

@@ Line 21: / Line 21: @@
 Do not use <tt>operator T()</tt> (where <tt>T</tt> is a type) to allow an implicit conversion to a different type. For example:
- t_string(const std::string&);
+<syntaxhighlight lang='c++'>
 This can cause many situations where a temporary t_string is implicitly created and then gets destroyed unexpectedly (reference [https://gna.org/bugs/index.php?20360 bug #20360]).
@@ Line 67: / Line 69: @@
 If a value passed to a function can never be <tt>NULL</tt>, use a reference instead of a pointer. For example:
- void my_function(T& obj);
+<syntaxhighlight lang='c++'>
 rather than
- void my_function(T* obj);
+<syntaxhighlight lang='c++'>
 This more clearly shows prospective users of the function that <tt>obj</tt> may never be <tt>NULL</tt>, without them having to consult documentation or the implementation of the function.
@@ Line 80: / Line 86: @@
 Always use <tt>const</tt> when you are not going to modify an object. For example:
- void my_function(const T& obj);
+<syntaxhighlight lang='c++'>
 This shows to the caller that <tt>obj</tt> will not be modified. If <tt>my_function()</tt> may modify <tt>obj</tt>, then use the following instead:
- void my_function(T& obj);
+<syntaxhighlight lang='c++'>
 Likewise, if a variable is not changed after initialization, make it <tt>const</tt>, and mark member functions as <tt>const</tt> if they do not modify their object.
@@ Line 92: / Line 102: @@
 If you assign something to a <tt>const</tt> reference of a different type, if necessary (if the type is different but there is a conversion) the compiler will create a temporary and guarantee it lasts for the lifetime of the reference. So
- char c = 0;
+<syntaxhighlight lang='c++'>
- const int& i = c;
+char c = 0;
- c = 5;
+const int& i = c;
 will result in c == 5 and i == 0, which may not be what you expect.
@@ Line 104: / Line 116: @@
 Code that uses a pattern like the following is bad:
+<syntaxhighlight lang='c++'>
-     SDL_Surface* image = IMG_Load("image.bmp");
-     ...some code, which uses 'image'...
+    SDL_Surface* image = IMG_Load("image.bmp");
-     SDL_FreeSurface(image);
+    // ...some code, which uses 'image'...
+    SDL_FreeSurface(image);
 The code may throw an exception, and <tt>image</tt> will never be freed. Instead, use wrapper objects which free the object in their destructor.
@@ Line 114: / Line 128: @@
 For <tt>SDL_Surface</tt> objects, the <tt>surface</tt> type is used throughout the Wesnoth source code to achieve this purpose. So you could rewrite the above code as follows:
+<syntaxhighlight lang='c++'>
-     surface image(IMG_Load("image.bmp"));
-     ...some code, which uses 'image'...
+    surface image(IMG_Load("image.bmp"));
- } ''the image is automatically freed here when 'image' is destroyed
+    // ...some code, which uses 'image'...
 Instead of allocating memory directly using <tt>new[]</tt> or <tt>malloc()</tt>, use language-provided containers, such as vector.
@@ Line 144: / Line 160: @@
 The following code,
- if(i->second.side() == (size_t)player_number_) {
+<syntaxhighlight lang='c++'>
 is considered bad practice in C++ since a C-style cast is overpowered -- if types change around it could end up casting away constness, or performing an implementation-defined data reinterpretation (basically a C-style cast is a compiler-generated combination of <tt>static_cast</tt>, <tt>reinterpret_cast</tt>, and <tt>const_cast</tt>).
@@ Line 150: / Line 168: @@
 This syntax,
- if(i->second.side() == size_t(player_number_)) {
+<syntaxhighlight lang='c++'>
 is also a cast, and [http://stackoverflow.com/a/32224 semantically identical] to the C-style cast. It should also be avoided.
@@ Line 156: / Line 176: @@
 Good programming style is to use the least powerful tool available that does what you want. For example:
- if(i->second.side() == static_cast<size_t>(player_number_)) {
+<syntaxhighlight lang='c++'>
 Alternatively, a constructor call may be used for non-built-in types.
@@ Line 166: / Line 188: @@
 <tt><nowiki>#</nowiki>define foo X</tt> is not a typesafe approach to define constants. Instead, you can something like the following (in an anonymous namespace) to achieve the same goal in a typesafe fashion.
- namespace {
+<syntaxhighlight lang='c++'>
-     const T foo = X;
+namespace {
+    const T foo = X;
 == Documentation ==

← Older revision		Revision as of 14:13, 13 January 2025
Line 124:		Line 124:

	For more information, you can read about the (important) RAII idiom: http://c2.com/cgi/wiki?ResourceAcquisitionIsInitialization		For more information, you can read about the (important) RAII idiom: http://c2.com/cgi/wiki?ResourceAcquisitionIsInitialization
−
−	~~=== Do not use sprintf ===~~
−
−	The <tt>sprintf()</tt> function does not check whether or not it is writing past the end of the space allocated. This is a security problem if someone other than the person running the game can cause <tt>sprintf()</tt> to write very long strings. In Wesnoth, this untrusted data could come potentially from other players in a multiplayer game, or from downloaded add-ons. Instead you should use <tt>snprintf()</tt> with the second argument being the <tt>sizeof</tt> of the buffer that will hold the result.

	== Standard C++ to avoid ==		== Standard C++ to avoid ==

← Older revision		Revision as of 06:48, 13 January 2025
Line 40:		Line 40:

	You can read more about the issue here: http://c2.com/cgi/wiki?BewareOfExceptionsInTheDestructor		You can read more about the issue here: http://c2.com/cgi/wiki?BewareOfExceptionsInTheDestructor
		+
		+	=== The empty brace initializer ===
		+
		+	The empty brace initializer should not be used indiscriminately if possible since it hurts readability.
		+
		+	<code>= {}</code> can be used to initialize list-like structures, but not points, rects or map_locations. In those cases, use a constructor call or at the very least, <code>point a = {0,0}</code> or <code>point a(0,0)</code>. This becomes more important in cases like this:
		+	<syntaxhighlight lang='c++'>
		+	last_loc_ = {};
		+	</syntaxhighlight>
		+	Now the person reading the code has no idea what type last_loc_ has, whereas
		+	<syntaxhighlight lang='c++'>
		+	last_loc_ = map_location(0,0);
		+	</syntaxhighlight>
		+	makes it much more obvious.

	== Naming ==		== Naming ==

@@ Line 3: / Line 3: @@
 == C++ version ==
-Wesnoth uses C++ conforming to C++11 in stable branch and C++17 (as supported by macOS 10.11+) in master branch.
+Wesnoth uses C++ conforming to C++17 (as supported by macOS 10.11+) in master branch.
 == Formatting ==

@@ Line 170: / Line 170: @@
 === Doxygen ===
-See [[Doxygen]] for tips on how to comment the code, so that Doxygen can nicely document it.
+All code comment documentation should be done using Doxygen formatting.  Online doxygen output can be found at https://devdocs.wesnoth.org/
 == See also ==

← Older revision		Revision as of 11:56, 27 August 2018
Line 10:		Line 10:

	You may use long lines.		You may use long lines.
		+
		+	Don't use a space after control flow keywords (if/for/...).

	== Evil things to avoid ==		== Evil things to avoid ==