From 611374f8683eb0ebd37124e77dcf108d3656bedd Mon Sep 17 00:00:00 2001 From: Owen Jones Date: Fri, 10 Aug 2018 10:42:45 +0100 Subject: [PATCH 1/2] Document classes and member variables unless obvious --- CODING_STANDARD.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/CODING_STANDARD.md b/CODING_STANDARD.md index 0d8fe0c8e81..8284a0294dd 100644 --- a/CODING_STANDARD.md +++ b/CODING_STANDARD.md @@ -59,12 +59,13 @@ Formatting is enforced using clang-format. For more information about this, see ``` Note that the `\file` tag must be immediately followed by a newline in order for Doxygen to relate the comment to the current file. -- Each function should be preceded by a Doxygen comment describing that - function. The format should match the [LLVM +- Each class, member variable and function should be preceded by a Doxygen + comment describing it when it is not immediately obvious what it does. The + format should match the [LLVM guidelines](http://llvm.org/docs/CodingStandards.html#doxygen-use-in-documentation-comments), - with one extension: `\param` and `\return` comments longer than a single line - should have subsequent lines indented by two spaces, so that the tags stand - out. An example: + with one extension: for functions, `\param` and `\return` comments longer than + a single line should have subsequent lines indented by two spaces, so that the + tags stand out. An example: ```c++ /// This sentence, until the first dot followed by whitespace, becomes /// the brief description. More detailed text follows. Feel free to From 519370dfa39332015320c5cf8798e1a82df21834 Mon Sep 17 00:00:00 2001 From: Owen Jones Date: Fri, 10 Aug 2018 11:03:02 +0100 Subject: [PATCH 2/2] State that identifiers should be good --- CODING_STANDARD.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CODING_STANDARD.md b/CODING_STANDARD.md index 8284a0294dd..98d8dc51386 100644 --- a/CODING_STANDARD.md +++ b/CODING_STANDARD.md @@ -94,6 +94,7 @@ Formatting is enforced using clang-format. For more information about this, see - Use #ifdef DEBUG to guard debug code # Naming +- Identifiers should make clear the purpose of the thing they are naming. - Identifiers may use the characters `[a-z0-9_]` and should start with a lower-case letter (parameters in constructors may start with `_`). - Omit names of parameters or exception objects when they are not used. If