diff --git a/project-guidelines.md b/project-guidelines.md index f43aa5b..5442fee 100644 --- a/project-guidelines.md +++ b/project-guidelines.md @@ -13,21 +13,96 @@ ## Commit messages Commit subject lines should not be longer than 72 characters. Each line in the body must not be longer than 80 characters. +Whether a commit requires more than a subject line is up to the developer's discretion. Another developer should be able to know _exactly_ what has changed by reading the commit. + ### Emoji Commit messages must start with an emoji relating to the nature of the commit, because emojis are fun. Emojis are put in commit messages with github shortcodes (e.g. :heart: is `:heart:`). [Emojipedia](https://emojipedia.org/) has the github shortcodes for all emoji. -There are no rules for which emoji to use where, but here are some inspiration: +There are no rules for which emoji to use where, but here's some inspiration: -:bug: (`:bug:`) - Fixing a bug +:bug: (`:bug:`) - Fixing a bug. + +:pencil: (`:pencil:`) - Adding to or changing `README.md`, documentation, logging code or other text. + +:stop_sign: (`:stop_sign:`) - Adding or changing code that deals with exceptions and errors. + +:sparkles: (`:sparkles:`) - Adding new feature. # Terminology +Comments, strings, variable names, class names, docstrings, as well as all other text in your code, filenames and directory names should use this terminology correctly. + +**cog** - A class that contains an amount of bot commands. + +**ctx** - The [context](https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#context) of a command. All command and error functions should use `ctx` as the context variable. + +**internal** - Functions, classes and methods that are only used by the bot and don't use the Discord API. # Code ## Code Style ++ All the Python code should follow the [PEP 8 guidelines](https://www.python.org/dev/peps/pep-0008/). + +### Documentation ++ Comment lines should not exede 72 characters. ++ There should be a comment for each import, explaining where the module is used. ++ Comments should explain things that are not obvious and not described in a docstring. + +### Docstrings ++ There should be a docstring defining every module, function, class and method for all Python code in Gwendolyn. ++ Obvious cases can be described in a single-line docstring, `"""Like this"""`. ++ Single-line docstrings should have the start- and end-quotations be on the same line. Multi-line docstrings should have the end-quotation on its own line: + ``` + """Like this + + Some docstring + """ + ``` ++ Class docstrings should define and describe all class attributes, and provide a list of class methods, showing input and output types. This information should be provided like this: + ``` + """Class docstring + + *Attributes* + ------------ + color : string + The color of the class. + dead : bool + Whether the class is dead or not. + + *Methods* + --------- + changeColor(newColor : str) -> bool + kill() -> bool + """ + ``` ++ Method and function docstrings should define and describe all parameters and what it returns, in the same format as the docstring above. ++ Module docstrings should define classes and functions in the module, in the same format as the docstring above. + +## Error Handling +Code called by a command should not have `try` and `except` statements. All errors should be raised to the `on_command_error()` or `Command.error()` functions, where they can be dealt with. ## Cogs +The `Command` methods in cogs should only exist to perform small tasks or call code from elsewhere in the Gwendolyn code. Therefore, a single `Command` method should not contain more than 3 lines of code and should not use any modules other than `Discord.py` and the Gwendolyn modules. -## Discord API +## Codebase Management +### Folders ++ `cogs/` contains the command cogs. ++ `funcs/` contains all functions and classes called on by the rest of the code. ++ `resources/` contains the images, lookup databases, fonts etc. that the rest of the code uses. -## Logging \ No newline at end of file +### Important files ++ `Gwendolyn.py` contains the Gwendolyn class and running it starts the bot. It should be lightweight and not more than 100 lines. + +## Logging +Things you should know about the logging: ++ The `logThis()` function can be found in `.funcs/miscFuncs.py. ++ It is used to log to the log-file (`gwendolyn.log`) and print to the command line. ++ The function can take either a list of strings or a string as its first parameter. If the parameter is a string, it is converted to a list of 1 string. ++ The first string in the list is printed. All strings in the list are logged to the log-file. ++ If the list is longer than 1 string, `(details in log)` is added to the printed string. ++ The level parameter is 20 by default, which means the level is `INFO`. 40 corresponds to a level of `ERROR`, and 10 corresponds to a level of `DEBUG`. ++ Logs of level `DEBUG` are not printed. ++ Logs of level `ERROR` should only be created in the `on_command_error()` or `Command.error()` functions. + +### Logging rules +1. There should be at most 3 `INFO` level logs while executing a single command. This includes the log created in the `on_command()` function in `Gwendolyn.py`, so your code for a command can at most make 2 logs of level `INFO`. `DEBUG` level logs should be used for all other logging. +1. Always provide the channel id if available. Although you shouldn't pass the channel id to a function purely to use it in logs.