diff --git a/docpages/advanced_reference/coding_style_standards.md b/docpages/advanced_reference/coding_style_standards.md index 521d1f4849..6885a1d1f4 100644 --- a/docpages/advanced_reference/coding_style_standards.md +++ b/docpages/advanced_reference/coding_style_standards.md @@ -18,28 +18,7 @@ This covers your standard Curly Braces (commonly known as squiggly brackets), an Curly Braces should be on the same line as the keyword, for example: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~cpp -void foo() { - if (a == b) { - c(); - } else { - d(); - } - - while (true) { - // ... - } - - switch (a) { - case 1: - c(); - break; - case 2: - d(); - break; - } -} -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +\include{cpp} coding_style_standards/curly_braces.cpp This applies to functions, `while` statements, `if` statements, lambdas, nearly anything that uses curly braces with statements! @@ -47,20 +26,12 @@ This applies to functions, `while` statements, `if` statements, lambdas, nearly Lists should have a space after the comma in parameter lists, and after opening brackets and before closing brackets except when calling a function, for example: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~cpp -std::vector clowns = { "pennywise", "bobo" }; - -evaluate_clown(clowns[0], evilness(2.5, factor)); -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +\include{cpp} coding_style_standards/lists.cpp ## Dot (.) Notation When using the dot notation repeatedly (For example, creating an embed.), you should start each `.function()` on a new line, as such: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~cpp -stuff{} - .add_stuff() - .add_stuff(); -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +\include{cpp} coding_style_standards/dot_notation.cpp ## Indentation @@ -74,33 +45,9 @@ Constants and macros should be all `UPPERCASE` with `SNAKE_CASE` to separate wor All comments should be in `doxygen` format (similar to javadoc). Please see existing class definitions for an example. You should use doxygen style comments in a class definition inside a header file. Be liberal with comments, especially if your code makes any assumptions! Comments should follow the format below: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~cpp -/** - * @brief This is a function that does some cool stuff. - * More stuff here will still go in brief! - * @warning This current does nothing! - */ -func_name(); - -/** - * @brief This turns a name into a meme name! - * - * @param name The name of the user that you want to meme-ify. - * @return a meme name! - */ -std::string name_to_meme(const std::string& name) const; - -int main() { - /* We are now going to do some cool stuff. */ - func_name(); - - /* Going to turn brain into a meme name. - * Why? - * Because why not. That's why. - */ - std::cout << name_to_meme("Brain") << "\n"; -} -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +\note Comments that contain doxygen stuff need to use two stars at the beginning (/**). This example doesn't because doxygen gets confused and doesn't show the comments. + +\include{cpp} coding_style_standards/comments.cpp ## Spell Checks @@ -110,13 +57,7 @@ To prevent typos, a GitHub-Action checks the documentation. If it fails for a wo If you export a class which is to be accessible to users, be sure to prefix it with the `DPP_EXPORT` macro, for example: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~cpp -class DPP_EXPORT my_new_class { -public: - int hats; - int clowns; -}; -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +\include{cpp} coding_style_standards/symbol_exporting.cpp The `DPP_EXPORT` macro ensures that on certain platforms (notably Windows) the symbol is exported to be available to the library user. @@ -160,33 +101,11 @@ If a value will only hold values up to 255, use `uint8_t`. If a value cannot hol Where possible, if you are adding methods to a class you should consider fluent design. Fluent design is the use of class methods that return a reference to self (via `return *this`), so that you can chain object method calls together (in the way dpp::message and dpp::embed do). For example: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~cpp -class DPP_EXPORT my_new_class { -public: - int hats; - int clowns; - - my_new_class& set_hats(int new_hats); - my_new_class& set_clowns(int new_clowns); -}; - -my_new_class& my_new_class::set_hats(int new_hats) { - hats = new_hats; - return *this; -} - -my_new_class& my_new_class::set_clowns(int new_clowns) { - clowns = new_clowns; - return *this; -} -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +\include{cpp} coding_style_standards/fluent_design.cpp This would allow the user to do this: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~cpp -dpp::my_new_class nc; -nc.set_hats(3).set_clowns(9001); -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +\include{cpp} coding_style_standards/fluent_design2.cpp ## Keep All D++ Related Types in the dpp Namespace diff --git a/docpages/example_code/coding_style_standards/comments.cpp b/docpages/example_code/coding_style_standards/comments.cpp new file mode 100644 index 0000000000..c172f087bf --- /dev/null +++ b/docpages/example_code/coding_style_standards/comments.cpp @@ -0,0 +1,27 @@ +/* + * @brief This is a function that does some cool stuff. + * More stuff here will still go in brief! + * @warning This does nothing! + */ +func_name(); + +/* + * @brief This turns a name into a meme name! + * + * @param name The name of the user that you want to meme-ify. + * @return a meme name! + */ +std::string name_to_meme(const std::string& name) const; + +/* -------------------- .cpp file -------------------- */ + +int main() { + /* We are now going to do some cool stuff. */ + func_name(); + + /* Going to turn brain into a meme name. + * Why? + * Because why not. That's why. + */ + std::cout << name_to_meme("Brain") << "\n"; +} \ No newline at end of file diff --git a/docpages/example_code/coding_style_standards/curly_braces.cpp b/docpages/example_code/coding_style_standards/curly_braces.cpp new file mode 100644 index 0000000000..9e7b28114a --- /dev/null +++ b/docpages/example_code/coding_style_standards/curly_braces.cpp @@ -0,0 +1,20 @@ +void foo() { + if (a == b) { + c(); + } else { + d(); + } + + while (true) { + // ... + } + + switch (a) { + case 1: + c(); + break; + case 2: + d(); + break; + } +} \ No newline at end of file diff --git a/docpages/example_code/coding_style_standards/dot_notation.cpp b/docpages/example_code/coding_style_standards/dot_notation.cpp new file mode 100644 index 0000000000..f9cfa84922 --- /dev/null +++ b/docpages/example_code/coding_style_standards/dot_notation.cpp @@ -0,0 +1,5 @@ +stuff{} + .add_stuff() + .add_stuff(); + +event.reply("This reply function isn't indented!"); \ No newline at end of file diff --git a/docpages/example_code/coding_style_standards/fluent_design.cpp b/docpages/example_code/coding_style_standards/fluent_design.cpp new file mode 100644 index 0000000000..dc7faa9d77 --- /dev/null +++ b/docpages/example_code/coding_style_standards/fluent_design.cpp @@ -0,0 +1,18 @@ +class DPP_EXPORT my_new_class { +public: + int hats; + int clowns; + + my_new_class& set_hats(int new_hats); + my_new_class& set_clowns(int new_clowns); +}; + +my_new_class& my_new_class::set_hats(int new_hats) { + hats = new_hats; + return *this; +} + +my_new_class& my_new_class::set_clowns(int new_clowns) { + clowns = new_clowns; + return *this; +} \ No newline at end of file diff --git a/docpages/example_code/coding_style_standards/fluent_design2.cpp b/docpages/example_code/coding_style_standards/fluent_design2.cpp new file mode 100644 index 0000000000..87223b126d --- /dev/null +++ b/docpages/example_code/coding_style_standards/fluent_design2.cpp @@ -0,0 +1,2 @@ +dpp::my_new_class nc; +nc.set_hats(3).set_clowns(9001); \ No newline at end of file diff --git a/docpages/example_code/coding_style_standards/lists.cpp b/docpages/example_code/coding_style_standards/lists.cpp new file mode 100644 index 0000000000..91abeac6a9 --- /dev/null +++ b/docpages/example_code/coding_style_standards/lists.cpp @@ -0,0 +1,3 @@ +std::vector clowns = { "pennywise", "bobo" }; + +evaluate_clown(clowns[0], evilness(2.5, factor)); \ No newline at end of file diff --git a/docpages/example_code/coding_style_standards/symbol_exporting.cpp b/docpages/example_code/coding_style_standards/symbol_exporting.cpp new file mode 100644 index 0000000000..19c8760d31 --- /dev/null +++ b/docpages/example_code/coding_style_standards/symbol_exporting.cpp @@ -0,0 +1,5 @@ +class DPP_EXPORT my_new_class { +public: + int hats; + int clowns; +}; \ No newline at end of file