diff --git a/docs/style/comments.md b/docs/style/comments.md index b7514f7..6e23986 100644 --- a/docs/style/comments.md +++ b/docs/style/comments.md @@ -40,6 +40,140 @@ Example: | **DEPRECATED** | as-of-date(dd/mm/yyyy) | Mark an API or function as deprecated. | `// DEPRECATED(19/06/2025): Replaced this function with Foo()` | | **WTF** | - | Identify confusing or unexpected behavior requiring investigation. *(Use sparingly.)* | `// WTF: Behavior differs between debug and release builds` | +--- + +## Doxygen Guidelines + +### 📍 Where to use? + +- At the **header** of every file, explaining: + - Filename + - Brief description of file's purpose and contents. + - Author(s) + - Date of Creation +- **Above** every **Method**, describing: + - The purpose briefly, in one line + - The method in more detail. (What algorithms were used, unique decisions made.) + - The parameter(s) and result. +- **Class/Struct** documenation: + - Brief class description + - Detailed usage information. + - Template parameters. + - Important Member relationships + +### :writing_hand: Writing Style guidelines + +**Grammar & Tone:** + +- Present tense + + | | | + |--|--| + | ❌ Bad | `The function will sort the array.`| + | ✅ Good| `Sorts the array using quicksort.`| + +- Active voice: *Subject + Verb + Object* + + | | | + |--|--| + | ❌ Bad | `The integer is modified by the method.`| + | ✅ Good| `The function modifies the integer.`| + +- Write in Third Person instead of First Person: + + | | | + |--|--| + | ❌ No usage of: I, me, we. | `# I calculate the average here.`
`# We initialize the module`| + | ✅ Use Third person| `Calculates the average of the values.`
`Initializes the communication module.`| + +- Be direct and concise, + +- Start summaries with a verb: + + | | | + |--|--| + | ❌ Bad | `This function is responsible for performing the task of data validation.` | + | ✅ Good| `Validates input data format.`| + +### TEMPLATES + +**File headers [C++ only]:** + + /** + * @file filename.cpp + * @brief Brief description of file purpose + * @author John Doe (optional) + * @date 2024-01-15 + * + * Detailed description of file contents, context, and usage... + * Can span multiple lines... + * + * @NOTE: ... Important notes about this file + * @WARNING: ... Any warnings for developers + */ + +**Method Documentation:** + +- C++: + + /** + * @brief One-line description of function purpose + * + * Detailed description including algorithm, edge cases, + * performance characteristics, etc. + * + * @param param1 Description of first parameter + * @param param2 Description of second parameter + * @return Description of return value + * / + +- C#: + + /// + /// Calculates the sum of two integers. + /// + /// The first integer operand. + /// The second integer operand. + /// The sum of the two integers. + public static int Add(int left, int right) + { + return left + right; + } + +**Class Documentation:** + +- C++ + + /** + * @class ClassName + * @brief Brief description of class purpose + * + * Detailed explanation of class responsibilities, usage patterns, + * and important design decisions. + * + * @param Description of template parameter requirements + */ + public class ClassName + { + // Class implementation + } + +- C#: + + /// + /// A summary about this class. + /// + /// + /// These remarks would explain more about this class. + /// In this example, these comments also explain the + /// general information about the derived class. + /// + public class MainClass + { + } + +- For more examples, look here: + --- ## Discouraged Comment Styles