From 21195d363a6b2dee967785bbba0128b641f1e2c7 Mon Sep 17 00:00:00 2001 From: Zetok Zalbavar Date: Mon, 20 Feb 2017 12:40:54 +0000 Subject: [PATCH] docs: slightly improve link formatting and remove trailing whitespaces --- CONTRIBUTING.md | 4 +- doc/coding_standards.md | 133 ++++++++++++++++++++-------------------- 2 files changed, 68 insertions(+), 69 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c844bf5a..0ee6ed109 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -349,7 +349,7 @@ git config --global commit.gpgsign true # Coding Guidelines -See [coding_standards.md][Coding Standards]. +See [coding_standards.md]. ## Limitations @@ -366,4 +366,4 @@ Symbols that should be forbidden for filenames under Windows: [pull request]: https://github.com/qTox/qTox/pulls [`test-pr.sh`]: /test-pr.sh -[Coding Standards]: https://github.com/qTox/qTox/blob/master/doc/coding_standards.md +[coding_standards.md]: /doc/coding_standards.md diff --git a/doc/coding_standards.md b/doc/coding_standards.md index 580980252..f2807c347 100644 --- a/doc/coding_standards.md +++ b/doc/coding_standards.md @@ -1,55 +1,55 @@ # Coding Standards & Guidelines -This document defines the qTox coding standards and style, all code +This document defines the qTox coding standards and style, all code contributions are expected to adhere to the rules described below. Most stylistic features described below are described as clang-format rules -present in the root of the repository, as such most code formatting rules can +present in the root of the repository, as such most code formatting rules can be applied by simply running clang-format over the source code in question. ## Coding Standard -qTox is written under **[ISO/IEC 14882:2011 (C++11)][ISO/IEC/C++11]** without -GNU/GCC specific extensions (i.e. qTox should compile with `CXXFLAGS` set to -`-std=c++11`, regardless of if `-std=gnu+11` is being used during compile -time). Source code must be able to be compiled under multiple different -compilers and operating systems including but not limited to GCC and Clang on +qTox is written under **[ISO/IEC 14882:2011 (C++11)][ISO/IEC/C++11]** without +GNU/GCC specific extensions (i.e. qTox should compile with `CXXFLAGS` set to +`-std=c++11`, regardless of if `-std=gnu+11` is being used during compile +time). Source code must be able to be compiled under multiple different +compilers and operating systems including but not limited to GCC and Clang on Microsoft Windows, Apple OS X and GNU/Linux-based derivatives. -In addition to the base language, the following additional restrictions are +In addition to the base language, the following additional restrictions are imposed: ### Compatibility -qTox is linked against Qt 5, allowing the use of Qt constructs and library +qTox is linked against Qt 5, allowing the use of Qt constructs and library features. The current minimum supported Qt version is Qt 5.3, meaning that all code must compile in a Qt 5.3 environment. Any usage post-Qt 5.3 features must be optional and be disabled when compiling/running in a Qt 5.3 environment. ### No Exceptions -qTox is compiled without support for [C++11 exceptions][Exceptions], meaning -that any code contribution or dependency cannot throw a C++ exception at -runtime or else the application will crash. For code present in the qTox -repository, this is enforced by the use of the `exceptions_off` qmake +qTox is compiled without support for [C++11 exceptions][Exceptions], meaning +that any code contribution or dependency cannot throw a C++ exception at +runtime or else the application will crash. For code present in the qTox +repository, this is enforced by the use of the `exceptions_off` qmake configuration. -Note: This restriction prohibits the use of external libraries that may throw -unhandled exceptions to qTox code. External libraries using exceptions, but +Note: This restriction prohibits the use of external libraries that may throw +unhandled exceptions to qTox code. External libraries using exceptions, but never require qTox code to handle them directly, will work fine. ### No RTTI qTox is compiled without support for [RTTI], as such code contributions using -`dynamic_cast()` or `std::dynamic_pointer_cast()` may fail to compile and may -be rejected on this basis. The implications of this are that the signature of -all polymorphic types must be known at compile time or stored in an -implementation-specific way. In essence, if a substitution from -`dynamic_cast()` to `static_cast()` can be performed without affecting program +`dynamic_cast()` or `std::dynamic_pointer_cast()` may fail to compile and may +be rejected on this basis. The implications of this are that the signature of +all polymorphic types must be known at compile time or stored in an +implementation-specific way. In essence, if a substitution from +`dynamic_cast()` to `static_cast()` can be performed without affecting program correctness, the construct in question is valid. -**Note: no usage of `dynamic_cast()` or `std::dynamic_pointer_cast()` is -permitted, even if the code compiles**. An optimizing compiler may be silently +**Note: no usage of `dynamic_cast()` or `std::dynamic_pointer_cast()` is +permitted, even if the code compiles**. An optimizing compiler may be silently replacing your dynamic casts with static casts if it can ensure the replacement is to the same effect. @@ -59,11 +59,11 @@ For manipulation of Qt-based objects, use `qobject_cast()` instead. ### Indentation -All code is to be formatted with an indentation size of 4 characters, using -spaces. **Tabs are not permitted.** Scope specifiers and namespaces are not to +All code is to be formatted with an indentation size of 4 characters, using +spaces. **Tabs are not permitted.** Scope specifiers and namespaces are not to be indented. -The following example demonstrates well formatted code under the indentation +The following example demonstrates well formatted code under the indentation rules: ```c++ @@ -97,11 +97,11 @@ public: ### Spacing -Spaces are to be added before the opening parenthesis of all control -statements. No spaces should be present preceeding or trailing in argument +Spaces are to be added before the opening parenthesis of all control +statements. No spaces should be present preceeding or trailing in argument lists, template specification, array indexing or between any set of brackets. -Spaces should additionally be present in between all binary, ternary and +Spaces should additionally be present in between all binary, ternary and assignment operators, but should **not** be present in unary operators between the operator and the operand. @@ -151,14 +151,14 @@ void bar(T a) ### Alignment -If an argument list is to be split into multiple lines, the subsequent -arguments must be aligned with the opening brace of the argument list. +If an argument list is to be split into multiple lines, the subsequent +arguments must be aligned with the opening brace of the argument list. Alignment should also be performed on multiline binary or ternary operations. -If multiple trailing inline comments are used, they should all be aligned +If multiple trailing inline comments are used, they should all be aligned together. -The following example demonstrates well formatted code under the alignment +The following example demonstrates well formatted code under the alignment rules: ```c++ @@ -178,24 +178,24 @@ void bar(int a, int b, int c, int d, int e, int f) ### Braces and Line Breaks -The line length limit is set to around 100 characters. This means that most -expressions approaching 100 characters should be broken into multiline -statements. Clang-format will attempt to target this limit, going over the +The line length limit is set to around 100 characters. This means that most +expressions approaching 100 characters should be broken into multiline +statements. Clang-format will attempt to target this limit, going over the limit slightly if there are tokens that should not be split. Comments should wrap around unless they include elements that cannot be split (e.g. URLs). Line breaks should be added before all opening braces and after all template -specializations except for the `extern "C"` specifier. Lambdas have special +specializations except for the `extern "C"` specifier. Lambdas have special rules that need to be handled seperately, see section below. Braces should be added for all control structures, even those whose bodies only contain a single line. -**Note: Clang-format does not have the ability to enforce brace presence, one -must manually ensure all braces are present before formatting via +**Note: Clang-format does not have the ability to enforce brace presence, one +must manually ensure all braces are present before formatting via clang-format.** -The following example demonstrates well formatted code under the braces and +The following example demonstrates well formatted code under the braces and line break rules: ```c++ @@ -232,10 +232,10 @@ void example(T veryLongArgumentName, T anotherVeryLongArgumentName, T aThirdVery ### Lambdas -Lambdas are to follow special break rules defined by clang-format. In -particular, if the lambda body contains a single statement and line length -permits, the lambda is to be treated as a single expression, represented in an -inlined format (i.e. no newlines). Or else, a newline is to be inserted +Lambdas are to follow special break rules defined by clang-format. In +particular, if the lambda body contains a single statement and line length +permits, the lambda is to be treated as a single expression, represented in an +inlined format (i.e. no newlines). Or else, a newline is to be inserted **after** the opening bracket. The following example demonstrates well formatted code under the lambda rules: @@ -263,23 +263,23 @@ auto compareAndUpdate = [](const int expect, int& actual, int& newVal) -> int { ### Pointers Pointers, references and rvalue references should be be aligned left, combining -with the type **when it is possible to do so**. What this means that in a -regular pointer declaration of variable `x` pointing to a type `T` should be +with the type **when it is possible to do so**. What this means that in a +regular pointer declaration of variable `x` pointing to a type `T` should be declared as `T* x;` where the \* glyph is placed next to the type `T` without any -spaces separating them. A space should be present between pointer type and the +spaces separating them. A space should be present between pointer type and the variable name except in the special cases described below. -Special cases exist when the pointer glyph and the variable needs to put in -parentheses such as when declaring pointers to C-style arrays and pointers to +Special cases exist when the pointer glyph and the variable needs to put in +parentheses such as when declaring pointers to C-style arrays and pointers to functions. In these cases, the pointer **should be combined with the variable** and placed one space away from the pointer type, see examples below. -As a reminder, usage of C-style arrays should be minimized and generally -restricted to interactions with C-based APIs present in external libraries. -Consider using the keyword `auto` to allow automatic type deduction by the +As a reminder, usage of C-style arrays should be minimized and generally +restricted to interactions with C-based APIs present in external libraries. +Consider using the keyword `auto` to allow automatic type deduction by the compiler to avoid long and messy type ids. -This rule should apply everywhere: function parameters, declarations, +This rule should apply everywhere: function parameters, declarations, constructor initializer lists, etc, applying even if the variable name is not specified. @@ -307,10 +307,10 @@ void foo(int* x, int&&); // Forward function declaration pointers and rvalue ref ### Unary Increment/Decrement -When the use of the prefix and postfix notation for increment and decrement +When the use of the prefix and postfix notation for increment and decrement operators yield the same effect (typical when the return value is ignored), the prefix notation is preferred to ensure a consistent style. This applies to all -uses of the increment/decrement operators, including those embedded in +uses of the increment/decrement operators, including those embedded in for-loops. A few examples of the usage of increment/decrement operators: @@ -331,7 +331,7 @@ if (a++ == 0) // Allowed since ++a is not equivalent. } ``` -**Note: Clang-format does not have the ability to enforce consistent +**Note: Clang-format does not have the ability to enforce consistent prefix/postfix choice, one must manually ensure the correct style is used.** ### Includes @@ -351,14 +351,14 @@ Include directives should include header files in the following order: | 4\* | Qt | Headers for Qt objects and functions. | | 5\* | Other | Headers for any other dependencies (external libraries, tox, C/C++ STL, system headers, etc. | -\* These headers should be included with angle bracket (e.g. +\* These headers should be included with angle bracket (e.g. `#include `). For better header sorting, consider additionally sorting headers in the "other" -category (category 5) in the following order: Tox, external libraries, C/C++ +category (category 5) in the following order: Tox, external libraries, C/C++ STL and system headers for a smaller include profile (this is not mandatory). -Newlines can be present between includes to indicate logical grouping, however +Newlines can be present between includes to indicate logical grouping, however be wary that clang-format does not sort includes properly this way, electing to sort each group individually according to the criteria defined above. @@ -398,21 +398,21 @@ extern "C" { ## Documentation -When adding new code to qTox also add doxygen style comments before the -implementation. If an old function is changed, make sure the existing +When adding new code to qTox also add doxygen style comments before the +implementation. If an old function is changed, make sure the existing documentation is updated to reflect the changes or if none exists, add it. -Always attempt to put the documentation at the point of implementation (i.e. +Always attempt to put the documentation at the point of implementation (i.e. put as much in the source `.cpp` files as possible and minimize clutter in `.h` files.) -The documentation style mandates the use of `/**` to start a doxygen style -comment, and having ` *` (space asterisk) on all lines following the starting -line. Doxygen keywords like `@brief`, `@param` and `@return` should be used +The documentation style mandates the use of `/**` to start a doxygen style +comment, and having ` *` (space asterisk) on all lines following the starting +line. Doxygen keywords like `@brief`, `@param` and `@return` should be used such that doxygen can intelligently generate the appropriate documentation. On all updates to master, doxygen comments are automatically generated for the -source code, available at [https://qtox.github.io/doxygen][Doxygen]. +source code, available at https://qtox.github.io/doxygen. ```C++ /*...license info...*/ @@ -464,7 +464,7 @@ static int example(int x, int y) ## No translatable HTML tags Do not put HTML in UI files, or inside Qt's `tr()`. Instead, you can embed HTML -directly into C++ in the following way, to make only the user-facing text +directly into C++ in the following way, to make only the user-facing text translatable: ```C++ @@ -476,4 +476,3 @@ someWidget->setTooltip(QStringLiteral("") + tr("Tra [ISO/IEC/C++11]: http://www.iso.org/iso/catalogue_detail.htm?csnumber=50372 [Exceptions]: https://en.wikipedia.org/wiki/C%2B%2B#Exception_handling [RTTI]: https://en.wikipedia.org/wiki/Run-time_type_information -[Doxygen]: https://qtox.github.io/doxygen/