StarMirror/qTox
1
0
Fork 0
mirror of https://github.com/qTox/qTox.git synced 2024-03-22 14:00:36 +08:00
Code Issues Projects Releases Wiki Activity

docs: slightly improve link formatting and remove trailing whitespaces

Browse Source
This commit is contained in:
Zetok Zalbavar 2017-02-20 12:40:54 +00:00
parent e4d40f11ed
commit 21195d363a
No known key found for this signature in database
GPG Key ID: C953D3880212068A
2 changed files with 68 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
CONTRIBUTING.md
View File

@ -349,7 +349,7 @@ git config --global commit.gpgsign true
# Coding Guidelines # Coding Guidelines
See [coding_standards.md][Coding Standards]. See [coding_standards.md].
## Limitations ## Limitations
@ -366,4 +366,4 @@ Symbols that should be forbidden for filenames under Windows:
[pull request]: https://github.com/qTox/qTox/pulls [pull request]: https://github.com/qTox/qTox/pulls
[`test-pr.sh`]: /test-pr.sh [`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

133
doc/coding_standards.md
View File

@ -1,55 +1,55 @@
# Coding Standards & Guidelines # 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. contributions are expected to adhere to the rules described below.
Most stylistic features described below are described as clang-format rules 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. be applied by simply running clang-format over the source code in question.
## Coding Standard ## Coding Standard
qTox is written under **[ISO/IEC 14882:2011 (C++11)][ISO/IEC/C++11]** without 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 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 `-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 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 compilers and operating systems including but not limited to GCC and Clang on
Microsoft Windows, Apple OS X and GNU/Linux-based derivatives. 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: imposed:
### Compatibility ### 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 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 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. be optional and be disabled when compiling/running in a Qt 5.3 environment.
### No Exceptions ### No Exceptions
qTox is compiled without support for [C++11 exceptions][Exceptions], meaning qTox is compiled without support for [C++11 exceptions][Exceptions], meaning
that any code contribution or dependency cannot throw a C++ exception at 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 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 repository, this is enforced by the use of the `exceptions_off` qmake
configuration. configuration.
Note: This restriction prohibits the use of external libraries that may throw Note: This restriction prohibits the use of external libraries that may throw
unhandled exceptions to qTox code. External libraries using exceptions, but unhandled exceptions to qTox code. External libraries using exceptions, but
never require qTox code to handle them directly, will work fine. never require qTox code to handle them directly, will work fine.
### No RTTI ### No RTTI
qTox is compiled without support for [RTTI], as such code contributions using 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 `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 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 all polymorphic types must be known at compile time or stored in an
implementation-specific way. In essence, if a substitution from implementation-specific way. In essence, if a substitution from
`dynamic_cast()` to `static_cast()` can be performed without affecting program `dynamic_cast()` to `static_cast()` can be performed without affecting program
correctness, the construct in question is valid. correctness, the construct in question is valid.
**Note: no usage of `dynamic_cast()` or `std::dynamic_pointer_cast()` is **Note: no usage of `dynamic_cast()` or `std::dynamic_pointer_cast()` is
permitted, even if the code compiles**. An optimizing compiler may be silently 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 replacing your dynamic casts with static casts if it can ensure the replacement
is to the same effect. is to the same effect.
@ -59,11 +59,11 @@ For manipulation of Qt-based objects, use `qobject_cast()` instead.
### Indentation ### Indentation
All code is to be formatted with an indentation size of 4 characters, using 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 spaces. **Tabs are not permitted.** Scope specifiers and namespaces are not to
be indented. be indented.
The following example demonstrates well formatted code under the indentation The following example demonstrates well formatted code under the indentation
rules: rules:
```c++ ```c++
@ -97,11 +97,11 @@ public:
### Spacing ### Spacing
Spaces are to be added before the opening parenthesis of all control Spaces are to be added before the opening parenthesis of all control
statements. No spaces should be present preceeding or trailing in argument statements. No spaces should be present preceeding or trailing in argument
lists, template specification, array indexing or between any set of brackets. 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 assignment operators, but should **not** be present in unary operators between
the operator and the operand. the operator and the operand.
@ -151,14 +151,14 @@ void bar(T a)
### Alignment ### Alignment
If an argument list is to be split into multiple lines, the subsequent 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. arguments must be aligned with the opening brace of the argument list.
Alignment should also be performed on multiline binary or ternary operations. 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. together.
The following example demonstrates well formatted code under the alignment The following example demonstrates well formatted code under the alignment
rules: rules:
```c++ ```c++
@ -178,24 +178,24 @@ void bar(int a, int b, int c, int d, int e, int f)
### Braces and Line Breaks ### Braces and Line Breaks
The line length limit is set to around 100 characters. This means that most The line length limit is set to around 100 characters. This means that most
expressions approaching 100 characters should be broken into multiline expressions approaching 100 characters should be broken into multiline
statements. Clang-format will attempt to target this limit, going over the 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 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). 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 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. rules that need to be handled seperately, see section below.
Braces should be added for all control structures, even those whose bodies only Braces should be added for all control structures, even those whose bodies only
contain a single line. contain a single line.
**Note: Clang-format does not have the ability to enforce brace presence, one **Note: Clang-format does not have the ability to enforce brace presence, one
must manually ensure all braces are present before formatting via must manually ensure all braces are present before formatting via
clang-format.** 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: line break rules:
```c++ ```c++
@ -232,10 +232,10 @@ void example(T veryLongArgumentName, T anotherVeryLongArgumentName, T aThirdVery
### Lambdas ### Lambdas
Lambdas are to follow special break rules defined by clang-format. In Lambdas are to follow special break rules defined by clang-format. In
particular, if the lambda body contains a single statement and line length 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 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 inlined format (i.e. no newlines). Or else, a newline is to be inserted
**after** the opening bracket. **after** the opening bracket.
The following example demonstrates well formatted code under the lambda rules: 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
Pointers, references and rvalue references should be be aligned left, combining 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 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 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 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. variable name except in the special cases described below.
Special cases exist when the pointer glyph and the variable needs to put in 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 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** functions. In these cases, the pointer **should be combined with the variable**
and placed one space away from the pointer type, see examples below. 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 As a reminder, usage of C-style arrays should be minimized and generally
restricted to interactions with C-based APIs present in external libraries. restricted to interactions with C-based APIs present in external libraries.
Consider using the keyword `auto` to allow automatic type deduction by the Consider using the keyword `auto` to allow automatic type deduction by the
compiler to avoid long and messy type ids. 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 constructor initializer lists, etc, applying even if the variable name is not
specified. specified.
@ -307,10 +307,10 @@ void foo(int* x, int&&); // Forward function declaration pointers and rvalue ref
### Unary Increment/Decrement ### 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 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 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. for-loops.
A few examples of the usage of increment/decrement operators: 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.** prefix/postfix choice, one must manually ensure the correct style is used.**
### Includes ### Includes
@ -351,14 +351,14 @@ Include directives should include header files in the following order:
| 4\* | Qt | Headers for Qt objects and functions. | | 4\* | Qt | Headers for Qt objects and functions. |
| 5\* | Other | Headers for any other dependencies (external libraries, tox, C/C++ STL, system headers, etc. | | 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 <cstdint>`). `#include <cstdint>`).
For better header sorting, consider additionally sorting headers in the "other" 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). 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 be wary that clang-format does not sort includes properly this way, electing to
sort each group individually according to the criteria defined above. sort each group individually according to the criteria defined above.
@ -398,21 +398,21 @@ extern "C" {
## Documentation ## Documentation
When adding new code to qTox also add doxygen style comments before the When adding new code to qTox also add doxygen style comments before the
implementation. If an old function is changed, make sure the existing implementation. If an old function is changed, make sure the existing
documentation is updated to reflect the changes or if none exists, add it. 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` put as much in the source `.cpp` files as possible and minimize clutter in `.h`
files.) files.)
The documentation style mandates the use of `/**` to start a doxygen style The documentation style mandates the use of `/**` to start a doxygen style
comment, and having ` *` (space asterisk) on all lines following the starting comment, and having ` *` (space asterisk) on all lines following the starting
line. Doxygen keywords like `@brief`, `@param` and `@return` should be used line. Doxygen keywords like `@brief`, `@param` and `@return` should be used
such that doxygen can intelligently generate the appropriate documentation. such that doxygen can intelligently generate the appropriate documentation.
On all updates to master, doxygen comments are automatically generated for the 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++ ```C++
/*...license info...*/ /*...license info...*/
@ -464,7 +464,7 @@ static int example(int x, int y)
## No translatable HTML tags ## No translatable HTML tags
Do not put HTML in UI files, or inside Qt's `tr()`. Instead, you can embed HTML 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: translatable:
```C++ ```C++
@ -476,4 +476,3 @@ someWidget->setTooltip(QStringLiteral("<html><!-- some HTML text -->") + tr("Tra
[ISO/IEC/C++11]: http://www.iso.org/iso/catalogue_detail.htm?csnumber=50372 [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 [Exceptions]: https://en.wikipedia.org/wiki/C%2B%2B#Exception_handling
[RTTI]: https://en.wikipedia.org/wiki/Run-time_type_information [RTTI]: https://en.wikipedia.org/wiki/Run-time_type_information
[Doxygen]: https://qtox.github.io/doxygen/