Recent changes to Coding rules

Coding rules modified by Ulf Lorenz

Ulf Lorenz — Sun, 01 Sep 2019 20:31:05 -0000

--- v11
+++ v12
@@ -11,11 +11,11 @@

 A few rules to make the code look pretty and somehow consistent:

-- Opening brackets always start on the line of the indenting clause (function declaration or if/for/while statement). An exception are constructors with initialisation lists, where it may start on the next line.
+- Opening brackets always start on the line of the indenting clause (if/for/while statement) or on the next line for function declarations. If the opening bracket on the same line looks confusing, put it on the next line for clarity, though.
 - The code following a flow control statement (if/for/while) should always be put in a separate code block (i.e., curly brackets), even if it is a single statement.
 - Document classes and functions with doxygen-style comments. Exceptions are functions that override those in a base class or are self-explanatory(basic getters, for example).
 - try to use as self-explaining function names as possible. We do not use punch cards any longer, so a function name may exceed 8 characters.
-- Use the new C++-11-style unified initialization wherever possible, i.e., with curly brackets instead of normal brackets for constructor parameters. It may be that the gtest ASSERT_XXX macros hiccup on this, then we have to adapt of course.
+- Use the new C++-11-style unified initialization wherever possible, i.e., with curly brackets instead of normal brackets for constructor parameters. The exception are tests, where the test macros sometimes do not like it; this you will notice.
 - put template parameters on a separate line
 - if you override a function, always declare this function with the "override" keyword
 - whenever possible, use the new C++-11 auto syntax. There are two exceptions to the rule: the type should be explicitly declared for primitive data types (to specify the precision), and for tensor classes (the tensor libraries uses some type-casting functions to guarantee coherence of data).
@@ -44,4 +44,3 @@
 - Make short self-explanatory tests. Every single test clause should usually have one assert statement (or a few that logically belong together, like checking both values of a pair).
 - if an assertion is not self-explanatory, add a failure message. Try to avoid that, though.
 - Always use the appropriate assert. E.g., if you check for equality, do not ASSERT_TRUE(x == y), but use ASSERT_EQ(x,y).
-- Try to avoid googlemock (slows down compilation considerably)

Coding rules modified by Ulf Lorenz

Ulf Lorenz — Fri, 28 Sep 2018 21:44:53 -0000

--- v10
+++ v11
@@ -19,11 +19,7 @@
 - put template parameters on a separate line
 - if you override a function, always declare this function with the "override" keyword
 - whenever possible, use the new C++-11 auto syntax. There are two exceptions to the rule: the type should be explicitly declared for primitive data types (to specify the precision), and for tensor classes (the tensor libraries uses some type-casting functions to guarantee coherence of data).
-- the order of functions in a class and in the associated test cases should match, and should generally be (for quicker browsing)
-    - constructors / destructor
-    - getters
-    - setters
-    - other functions
+- never hold onto a std::function object. It may refer to Python objects/functions, in which case there may be lifetime issues. If a std::function is given as function argument, it must be used directly in the called function.

 Design
 ------

Coding rules modified by Ulf Lorenz

Ulf Lorenz — Thu, 23 Mar 2017 12:13:51 -0000

--- v9
+++ v10
@@ -36,6 +36,7 @@
 - Code should be typically defensive, and capture errors aggressively
 - Try to be aggressive with making functions const, and using const references as arguments.
 - Make functions short (<= 20 lines or so), and seriously consider redesigning if this does not work.
+- As a general rule, use forward declarations in header files instead of including other headers. Try to encapsulate external dependencies and do not include then in the header (exception: the tensor library) to keep compile times short.

 Testing
@@ -45,5 +46,6 @@

 - Use asserts instead of expects; if a test fails, it should fail hard.
 - Make short self-explanatory tests. Every single test clause should usually have one assert statement (or a few that logically belong together, like checking both values of a pair).
-- if an assertion is not self-explanatory, add a failure message.
+- if an assertion is not self-explanatory, add a failure message. Try to avoid that, though.
 - Always use the appropriate assert. E.g., if you check for equality, do not ASSERT_TRUE(x == y), but use ASSERT_EQ(x,y).
+- Try to avoid googlemock (slows down compilation considerably)

Coding rules modified by

Tue, 25 Nov 2014 21:01:35 -0000

--- v8
+++ v9
@@ -15,10 +15,15 @@
 - The code following a flow control statement (if/for/while) should always be put in a separate code block (i.e., curly brackets), even if it is a single statement.
 - Document classes and functions with doxygen-style comments. Exceptions are functions that override those in a base class or are self-explanatory(basic getters, for example).
 - try to use as self-explaining function names as possible. We do not use punch cards any longer, so a function name may exceed 8 characters.
-- Use the new C++-11-style unified initialization wherever possible, i.e., with curly brackets instead of normal brackets for constructor parameters. Exception are the gtest ASSERT_XXX macros, which seem to hiccup on this.
+- Use the new C++-11-style unified initialization wherever possible, i.e., with curly brackets instead of normal brackets for constructor parameters. It may be that the gtest ASSERT_XXX macros hiccup on this, then we have to adapt of course.
 - put template parameters on a separate line
 - if you override a function, always declare this function with the "override" keyword
 - whenever possible, use the new C++-11 auto syntax. There are two exceptions to the rule: the type should be explicitly declared for primitive data types (to specify the precision), and for tensor classes (the tensor libraries uses some type-casting functions to guarantee coherence of data).
+- the order of functions in a class and in the associated test cases should match, and should generally be (for quicker browsing)
+    - constructors / destructor
+    - getters
+    - setters
+    - other functions

 Design
 ------

Coding rules modified by

Sun, 30 Mar 2014 11:21:50 -0000

--- v7
+++ v8
@@ -15,10 +15,10 @@
 - The code following a flow control statement (if/for/while) should always be put in a separate code block (i.e., curly brackets), even if it is a single statement.
 - Document classes and functions with doxygen-style comments. Exceptions are functions that override those in a base class or are self-explanatory(basic getters, for example).
 - try to use as self-explaining function names as possible. We do not use punch cards any longer, so a function name may exceed 8 characters.
-- Use the new C++-11-style unified initialization wherever possible, i.e., with curly brackets instead of normal brackets for constructor parameters.
+- Use the new C++-11-style unified initialization wherever possible, i.e., with curly brackets instead of normal brackets for constructor parameters. Exception are the gtest ASSERT_XXX macros, which seem to hiccup on this.
 - put template parameters on a separate line
 - if you override a function, always declare this function with the "override" keyword
-
+- whenever possible, use the new C++-11 auto syntax. There are two exceptions to the rule: the type should be explicitly declared for primitive data types (to specify the precision), and for tensor classes (the tensor libraries uses some type-casting functions to guarantee coherence of data).

 Design
 ------

Coding rules modified by

Sun, 20 Oct 2013 12:50:37 -0000

--- v6
+++ v7
@@ -15,8 +15,9 @@
 - The code following a flow control statement (if/for/while) should always be put in a separate code block (i.e., curly brackets), even if it is a single statement.
 - Document classes and functions with doxygen-style comments. Exceptions are functions that override those in a base class or are self-explanatory(basic getters, for example).
 - try to use as self-explaining function names as possible. We do not use punch cards any longer, so a function name may exceed 8 characters.
-- Use the new C++-11-style unified initialization, i.e., with curly brackets instead of normal brackets for constructor parameters.
+- Use the new C++-11-style unified initialization wherever possible, i.e., with curly brackets instead of normal brackets for constructor parameters.
 - put template parameters on a separate line
+- if you override a function, always declare this function with the "override" keyword

 Design

Coding rules modified by

Sat, 07 Sep 2013 21:03:39 -0000

--- v5
+++ v6
@@ -3,7 +3,7 @@
 TDD
 ---

-The most important coding rule is the use of test-driven development (TDD). This is explained in depth on [another page](http://sourceforge.net/p/freelords/wiki/Coding Rules), and is *mandatory*.
+The most important single coding rule is the use of test-driven development (TDD). This is explained in depth on [another page](http://sourceforge.net/p/freelords/wiki/Coding Rules), and is *mandatory*.

 Coding
@@ -15,6 +15,7 @@
 - The code following a flow control statement (if/for/while) should always be put in a separate code block (i.e., curly brackets), even if it is a single statement.
 - Document classes and functions with doxygen-style comments. Exceptions are functions that override those in a base class or are self-explanatory(basic getters, for example).
 - try to use as self-explaining function names as possible. We do not use punch cards any longer, so a function name may exceed 8 characters.
+- Use the new C++-11-style unified initialization, i.e., with curly brackets instead of normal brackets for constructor parameters.
 - put template parameters on a separate line

@@ -34,6 +35,9 @@
 Testing
 -------

-- Always use asserts instead of expects; if a test fails, it should fail hard.
-- Every assert should have an error message to make clear what is tested.
-- Always use the appropriate assert. If you check for equality, do not assert true (x == y), but use the equality assertion. Same for floating points, use the appropriate assert statements.
+Coding rules specific to tests:
+
+- Use asserts instead of expects; if a test fails, it should fail hard.
+- Make short self-explanatory tests. Every single test clause should usually have one assert statement (or a few that logically belong together, like checking both values of a pair).
+- if an assertion is not self-explanatory, add a failure message.
+- Always use the appropriate assert. E.g., if you check for equality, do not ASSERT_TRUE(x == y), but use ASSERT_EQ(x,y).

Coding rules modified by

Sat, 07 Sep 2013 20:58:36 -0000

--- v4
+++ v5
@@ -15,10 +15,20 @@
 - The code following a flow control statement (if/for/while) should always be put in a separate code block (i.e., curly brackets), even if it is a single statement.
 - Document classes and functions with doxygen-style comments. Exceptions are functions that override those in a base class or are self-explanatory(basic getters, for example).
 - try to use as self-explaining function names as possible. We do not use punch cards any longer, so a function name may exceed 8 characters.
+- put template parameters on a separate line

 Design
 ------
+
+Some guidelines when creating new classes and such:
+
+- Use abstract base classes for marker interfaces as in Java from which you then derive the implementations.
+- Try to avoid creating templated classes or functions.
+- All references between entities should be via pointers, and all such pointers should be wrapped in shared_ptr. This relieves the final user of most memory management. Also, use std::make_shared as default when creating objects (e.g., in tests).
+- Code should be typically defensive, and capture errors aggressively
+- Try to be aggressive with making functions const, and using const references as arguments.
+- Make functions short (<= 20 lines or so), and seriously consider redesigning if this does not work.

 Testing

Coding rules modified by

Sat, 07 Sep 2013 20:52:25 -0000

--- v3
+++ v4
@@ -6,17 +6,19 @@
 The most important coding rule is the use of test-driven development (TDD). This is explained in depth on [another page](http://sourceforge.net/p/freelords/wiki/Coding Rules), and is *mandatory*.

-Code layout
------------
-
-- Opening brackets always start on the line of the indenting clause, i.e., directly after the if, function definition etc.
-- Every clause should always be put in opening brackets, even if it is only a single line.
-
-
 Coding
 ------

-- Code should generally be documented. If the function overrides one in a base class or is trivial to the point of self-explanatory (basic getters, for example), this may be left out. Every class should be documented as well.
+A few rules to make the code look pretty and somehow consistent:
+
+- Opening brackets always start on the line of the indenting clause (function declaration or if/for/while statement). An exception are constructors with initialisation lists, where it may start on the next line.
+- The code following a flow control statement (if/for/while) should always be put in a separate code block (i.e., curly brackets), even if it is a single statement.
+- Document classes and functions with doxygen-style comments. Exceptions are functions that override those in a base class or are self-explanatory(basic getters, for example).
+- try to use as self-explaining function names as possible. We do not use punch cards any longer, so a function name may exceed 8 characters.
+
+
+Design
+------

 Testing

WikiPage Coding rules modified by

Fri, 22 Mar 2013 17:21:53 -0000

--- v2
+++ v3
@@ -1,3 +1,27 @@
-The most important coding rule is the use of test-driven development (TDD). This is explained in depth on [another page](http://sourceforge.net/p/freelords/wiki/Coding Rules).
+Coding rules are subject to change over time, whenever we come across something that needs to be defined properly. In case of doubt, the existing code should give a best practice suggestion.

-Apart from that, the coding rules will evolve as we write the code. So far, there is only a hazy scheme that advanced, difficult to read and/or test techniques will not be used (i.e., no template metaprogramming and similar things). Furthermore, the code should be well readable and documented.
+TDD
+---
+
+The most important coding rule is the use of test-driven development (TDD). This is explained in depth on [another page](http://sourceforge.net/p/freelords/wiki/Coding Rules), and is *mandatory*.
+
+
+Code layout
+-----------
+
+- Opening brackets always start on the line of the indenting clause, i.e., directly after the if, function definition etc.
+- Every clause should always be put in opening brackets, even if it is only a single line.
+
+
+Coding
+------
+
+- Code should generally be documented. If the function overrides one in a base class or is trivial to the point of self-explanatory (basic getters, for example), this may be left out. Every class should be documented as well.
+
+
+Testing
+-------
+
+- Always use asserts instead of expects; if a test fails, it should fail hard.
+- Every assert should have an error message to make clear what is tested.
+- Always use the appropriate assert. If you check for equality, do not assert true (x == y), but use the equality assertion. Same for floating points, use the appropriate assert statements.