Mercurial > template

changeset 27:0706d01e073f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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   |
+```