Mercurial > template
changeset 27:0706d01e073f
Update markdown convention and add it to STYLE.md
author | David Demelier <markand@malikania.fr> |
---|---|
date | Fri, 25 May 2018 15:49:08 +0200 |
parents | 9d24e37a289c |
children | 1a9a76f94955 |
files | CHANGES.md CONTRIBUTE.md INSTALL.md README.md STYLE.md |
diffstat | 5 files changed, 274 insertions(+), 182 deletions(-) [+] |
line wrap: on
line diff
--- a/CHANGES.md Thu May 24 14:57:32 2018 +0200 +++ b/CHANGES.md Fri May 25 15:49:08 2018 +0200 @@ -7,5 +7,5 @@ project name 1.0.0 2017-12-25 ----------------------------- - - Some topic, - - Other topics. +- Some topic, +- Other topics.
--- a/CONTRIBUTE.md Thu May 24 14:57:32 2018 +0200 +++ b/CONTRIBUTE.md Fri May 25 15:49:08 2018 +0200 @@ -6,9 +6,9 @@ You may submit a patch when: - - You want to fix a bug / typo, - - You want to add a new feature, - - You want to change something. +- You want to fix a bug / typo, +- You want to add a new feature, +- You want to change something. There a lot of steps before submitting a patch. First, be sure to respect the style defined in the STYLE.md file. We never accept patches that do not match @@ -52,10 +52,10 @@ More options are available, see: - - `hg help hgrc.email`, - - `hg help hgrc.smtp`, - - `hg help patchbomb` - - `hg help email` +- `hg help hgrc.email`, +- `hg help hgrc.smtp`, +- `hg help patchbomb` +- `hg help email` ### Note to GMail users @@ -63,9 +63,9 @@ troubles with the `hg email` command, you must create a specific application password. - 1. Go to https://security.google.com/settings/security/apppasswords - 2. Create an application password, it will be auto generated, - 3. Use this password or store it directly in the `smtp.password` option. +1. Go to https://security.google.com/settings/security/apppasswords +2. Create an application password, it will be auto generated, +3. Use this password or store it directly in the `smtp.password` option. Use the following settings: @@ -87,6 +87,21 @@ **Note**: the recommended way is to create one unique revision. +### Commit messages + +Commit messages are written using the following syntax: + + Topic: short message less than 80 characters + + Optional additional description if needed. + +Replace `Topic` with one of the following: + +- **CMake**: for the build system, +- **Docs**: for the documentation, +- **Misc**: for miscellaneous files, +- **Tests**: for the unit tests. + ### Quick way If you plan to create a very small patch that consists of several lines, you can
--- a/INSTALL.md Thu May 24 14:57:32 2018 +0200 +++ b/INSTALL.md Fri May 25 15:49:08 2018 +0200 @@ -6,12 +6,12 @@ Requirements ------------ - - [Library](http://example.org), Short description, - - [Tool](http://example.org), Short description, +- [Library](http://example.org), Short description, +- [Tool](http://example.org), Short description, Optional: - - [Library](http://example.org), Short recommandation, +- [Library](http://example.org), Short recommandation, Basic installation ------------------
--- a/README.md Thu May 24 14:57:32 2018 +0200 +++ b/README.md Fri May 25 15:49:08 2018 +0200 @@ -14,6 +14,6 @@ Contributors ------------ - - Contributor 1, - - Contributor 2, - - Contributor 3. +- Contributor 1, +- Contributor 2, +- Contributor 3.
--- a/STYLE.md Thu May 24 14:57:32 2018 +0200 +++ b/STYLE.md Fri May 25 15:49:08 2018 +0200 @@ -1,52 +1,60 @@ PROJECT NAME CODING STYLE ========================= +General +======= + +- Always use 4 spaces as indentation (expect Makefiles), +- Use UTF-8 charset, +- Use Unix line endings, +- Never write two blank consecutives blank lines, + C++ === Style ----- - - Always use 4 spaces as indentation, - - Use UTF-8 charset, - - Use Unix line endings, - - Do not exceed 120 characters for lines of code, - - Do not exceed 80 characters for comments, - - Never write two blank consecutives blank lines, - - Do not use bad words. +- Do not exceed 120 characters for lines of code, +- Do not exceed 80 characters for comments, ### Braces Braces follow the K&R style, they are never placed on their own lines except for function definitions. -Do not put braces for single line statements except for clarity. - - if (condition) { - apply(); - add(); - } else - ok(); +Do not put braces for single line statements. - if (condition) - validate(); +```cpp +if (condition) { + apply(); + add(); +} else + ok(); - if (foo) { - state = long + conditional + that + requires + several + lines + +if (condition) + validate(); + +if (foo) + state = long + conditional + that + requires + several + lines + to + complete; - } +``` Functions require braces on their own lines. - void function() - { - } +```cpp +void function() +{ +} +``` And a lambda has its braces on the same lines too: - sort([&] (auto&) { - return true; - }); +```cpp +sort([&] (auto&) { + return true; +}); +``` ### Spaces @@ -55,60 +63,68 @@ Normal function calls do not require it. - if (foo) - destroy(sizeof (int)); +```cpp +if (foo) + destroy(sizeof (int)); +``` ### References and pointers References and pointers are always next to the type name and not the variable. - T& get(const std::string& name); +```cpp +T& get(const std::string& name); - int* p = &x; +int* p = &x; +``` ### Naming - - English names, - - Member variables have trailing underscore (e.g foo\_bar\_), - - No hungarian notation. +- English names, +- Member variables have trailing underscore (e.g foo\_bar\_), +- No hungarian notation. Everything is in `underscore_case` except template parameters and macros. - #if defined(FOO) - # include <foo.hpp> - #endif +```cpp +#if defined(FOO) +# include <foo.hpp> +#endif - namespace baz { +namespace baz { - class object { - private: - std::string name_; +class object { +private: + std::string name_; - public: - inline const std::string& name() const noexcept - { - return name_; - } - }; +public: + inline const std::string& name() const noexcept + { + return name_; + } +}; - template <typename Archive> - void open(const Archive& ar) - { - bool is_valid = false; - } +template <typename Archive> +void open(const Archive& ar) +{ + bool is_valid = false; +} - } // !baz +} // !baz +``` ### Header guards Do not use `#pragma once`. -Header guards are usually named **PROJECT_COMPONENT_FILENAME_HPP**. +Header guards are usually named `PROJECT_COMPONENT_FILENAME_HPP`. - #ifndef FOO_COMMON_UTIL_HPP - #define FOO_COMMON_UTIL_HPP +```cpp +#ifndef FOO_COMMON_UTIL_HPP +#define FOO_COMMON_UTIL_HPP - #endif // !FOO_COMMON_UTIL_HPP +#endif // !FOO_COMMON_UTIL_HPP +``` ### Enums @@ -117,29 +133,33 @@ Enum class are encouraged. - enum class color { - blue, - red, - green - }; +```cpp +enum class color { + blue, + red, + green +}; +``` ### Switch In a switch case statement, you **must** not declare variables and not indent cases. - switch (variable) { - case foo: - do_some_stuff(); - break; - default: - break; - } +```cpp +switch (variable) { +case foo: + do_some_stuff(); + break; +default: + break; +} +``` ### Files - - Use `.cpp` and `.hpp` as file extensions, - - Filenames are all lowercase. +- Use `.cpp` and `.hpp` as file extensions, +- Filenames are all lowercase. ### Comments @@ -147,53 +167,44 @@ like this. However any public function in the .hpp **must** be documented as doxygen without exception. - /* - * Multi line comments look like - * this. - */ +```cpp +/* + * Multi line comments look like + * this. + */ - // Short comment +// Short comment +``` Use `#if 0` to comment blocks of code. +```cpp #if 0 broken_stuff(); #endif +``` ### Includes The includes should always come in the following order. - 1. C++ headers - 2. C header - 3. Third party libraries - 4. Application headers in "" +1. C++ headers +2. C header +3. Third party libraries +4. Application headers in "" - #include <cstring> - #include <cerrno> - - #include <sys/stat.h> - - #include <libircclient.h> - - #include "foo.h" +```cpp +#include <cstring> +#include <cerrno> -**Note**: always use C++ headers for C equivalent, stdio.h -> cstdio, etc. - -### Commit messages +#include <sys/stat.h> -Commit messages are written using the following syntax: - - Topic: short message less than 80 characters +#include <libircclient.h> - Optional additional description if needed. - -Replace `Topic` with one of the following: +#include "foo.h" +``` - - **CMake**: for the build system, - - **Docs**: for the documentation, - - **Misc**: for miscellaneous files, - - **Tests**: for the unit tests. +Note: always use C++ headers for C equivalent, stdio.h -> cstdio, etc. Programming ----------- @@ -214,18 +225,22 @@ non-const reference as output parameter is **discouraged** and should be avoided in many case because it does not allow chaining of expressions like: - std::cout << reverse(upper(clean(" hello world! "))) << std::endl; +```cpp +std::cout << reverse(upper(clean(" hello world! "))) << std::endl; +``` If your function is designed to return a modified value passed as argument, it is better to take it by value and modify it directly. - std::string clean(std::string input) - { - if (!input.empty() && input.back() == '\r') - input.pop_back(); +```cpp +std::string clean(std::string input) +{ + if (!input.empty() && input.back() == '\r') + input.pop_back(); - return input; - } + return input; +} +``` Never pass primitive types as const value. @@ -237,26 +252,30 @@ For example, you may use `assert` to verify that the developer access the data between the bounds of an array: - T& operator[](unsigned index) - { - assert(index < length_); +```cpp +T& operator[](unsigned index) +{ + assert(index < length_); - return data_[index]; - } + return data_[index]; +} +``` The `assert` macro is not meant to check that a function succeeded, this code must not be written that way: - assert(listen(10)); +```cpp +assert(listen(10)); +``` ### Exceptions You must use exceptions to indicate an error that was unexpected such as: - - Failing to open a file, - - I/O unexpected errors, - - Parsing errors, - - User errors. +- Failing to open a file, +- I/O unexpected errors, +- Parsing errors, +- User errors. You may use the C++ standard exceptions defined in the stdexcept header but if you need to carry more data within your exception, you should derive from @@ -274,66 +293,80 @@ Example: - namespace util { +```cpp +namespace util { - std::string clean(std::string input); +std::string clean(std::string input); - } // !util +} // !util +``` ### Variables initialization Use parentheses to initialize non primitive types: - throw std::runtime_error("foo"); +```cpp +throw std::runtime_error("foo"); - my_class obj("bar"); +my_class obj("bar"); +``` Use brace initialization when you want to use an initializer list, type elision: - std::vector<int> v{1, 2, 3}; +```cpp +std::vector<int> v{1, 2, 3}; - foo({1, 2}); // type deduced +foo({1, 2}); // type deduced - return { "true", false }; // std::pair returned +return { "true", false }; // std::pair returned +``` Use the assignment for primitive types: - int x = 123; - bool is_valid = true; +```cpp +int x = 123; +bool is_valid = true; +``` ### Classes Classes are usually defined in the following order: - 1. Public inner types (enums, classes), - 2. Protected/private members - 3. Public functions +1. Public inner types (enums, classes), +2. Protected/private members and functions +3. Public static functions. +3. Public member functions +4. Public virtual functions. - class foo { - public: - enum class type { - a, - b - }; +```cpp +class foo { +public: + enum class type { + a, + b + }; - private: - int member_{0}; +private: + int member_{0}; - public: - void some_function(); - }; +public: + void some_function(); +}; +``` ### Structs Do not use C structs unless you have very good reason to do so. If you want to pack some data, just use `class` and make all fields public. - class point { - public: - int x{0}; - int y{0}; - }; +```cpp +class point { +public: + int x{0}; + int y{0}; +}; +``` ### Return @@ -342,22 +375,24 @@ This code is preferred: - if (a_condition_is_not_valid) - return nullptr; - if (an_other_condition) - return nullptr; +```cpp +if (a_condition_is_not_valid) + return nullptr; +if (an_other_condition) + return nullptr; - auto x = std::make_shared<object>(); +auto x = std::make_shared<object>(); - x->start(); - x->save(); +x->start(); +x->save(); - return x; +return x; +``` Additional rules: - - Do never put parentheses between the returned value, - - Do not put a else branch after a return. +- Do never put parentheses between the returned value, +- Do not put a else branch after a return. ### Auto @@ -385,11 +420,7 @@ Style ----- - - Always use 4 spaces as indentation, - - Use UTF-8 charset, - - Use Unix line endings, - - Try to keep line shorter than 80 columns - - Never write two blank consecutives blank lines. +- Try to keep line shorter than 80 columns ### Spaces @@ -467,10 +498,10 @@ The following commands must be avoided as much as possible: - - `link_directories`, - - `link_libraries`, - - `include_directories`, - - `add_definitions`. +- `link_directories`, +- `link_libraries`, +- `include_directories`, +- `add_definitions`. They pollute the global namespace, all targets defined after these commands will be built against those settings. Instead, you should use the per-targets @@ -504,3 +535,49 @@ add_executable(myapp ${FILES}) ``` + +Markdown +======== + +Lists +----- + +Use hyphens for unordered lists for consistency, do not indent top level lists, +then indent by two spaces each level + +```markdown +- unordered list 1 +- unordered list 2 + - sub unordered item + +1. unordered list 1 +2. unordered list 2 + 2.1. sub unordered item +``` + +Code blocks +----------- + +You can use three backticks and the language specifier or just indent a block by +for leading spaces if you don't need syntax. + + ```cpp + std::cout << "hello world" << std::endl; + ``` + +And without syntax: + +```markdown + This is simple code block. +``` + +Tables +------ + +Tables are supported and formatted as following: + +```markdown +| header 1 | header 2 | +|----------|----------| +| item 1 | item 2 | +```