Gwendolyn/project-guidelines.md

Git

Workflow rules

1. Coding on Gwendolyn is performed in feature branch workflow. This means all code should be added in a separate feature branch before it's added to the master branch.
2. Feature branches must be created from current master branch when
3. Never push to the master branch. All code from feature branches should be added with pull requests. NikolajDanger is the only developer who can accept pull requests to master.
4. All code pushed to master must:
   • Work
   • Be reachable when the bot is running
   • Follow the code style guidelines laid out later in this doc.
5. Code pushed to feature branches require none of those.

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. ❤️ is :heart:). Emojipedia has the github shortcodes for all emoji.

There are no rules for which emoji to use where, but here's some inspiration:

🐛 (:bug:) - Fixing a bug.

📝 (:pencil:) - Adding to or changing README.md, documentation, logging code or other text.

🛑 (:stop_sign:) - Adding or changing code that deals with exceptions and errors.

✨ (: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.

bot - The current discord client and instance of the Gwendolyn class.

cog - A class that contains an amount of bot commands.

ctx - The context of a command. All command and error functions should use ctx as the context variable.

utils - 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, with the following differences:

• Variable and function names must be camelCase, and must fully consist of either full words or common/understandable abbreviations.
• Use f-strings when applicable.

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. If a cog method calls a function in Gwendolyn, ctx must be passed, and the function should handle sending messages.

Codebase Management

Folders

• cogs/ contains the command cogs.
• funcs/ contains all functions and classes called on to perform commands. All functions must be accessible through a class, of which the Gwendolyn class has an instance as an attribute.
• resources/ contains the images, lookup databases, fonts etc. that the rest of the code uses.

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:

• log() is a method of the Gwendolyn class.
• 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 25 corresponds to print.
• Logs of level INFO are not printed.
• Logs of level ERROR should only be created in the on_command_error(), on_error() or Command.error() functions.

Logging rules

1. Never call the logThis() function from /utils/utilFuncs/. Always call bot.log.
2. The on_slash_command() and on_ready() events are the only times log should be called at level 25. INFO level logs should be used for all other logging.
3. Always provide the channel id if available. Although you shouldn't pass the channel id to a function purely to use it in logs.