Style Guide

Not Final.

If there is a conflict between the file you are working on, and this guide, opt for the style followed in the file. Additionally, make an issue on GitHub, requesting that the file be refactored to fit this guide. The more of the project following the same style, the better. (Though with the plugins, some differing styles is to be expected)

Python Version

This code base uses python 3 and only python 3. If you do not submit python 3 code your pull request will be ignored.

Code lay-out

Code Blocks

• Absolutely no one-line if statements or for and while loops. They hide meaning from other developers, making debugging and refactoring difficult.

String Formatting

• As of Python 3000, the "format" % var method of string formatting has been deemed as "not recommended". This means that the new, Python 3 formatting method "format".format(var) is to be used.

Indentation

• All indentation is to be in tabs. People inherently have different preferences, and tabs works around this.
• Recommended tab size is 4 columns. However, code should not be written such that changing the tab size will effect readability.

Maximum line length

• There is none. Seriously, this isn't the 60s anymore.
• It is recommended that you keep lines (not including indentation) under 100 characters, primarily to prioritise simple and readable code. Don't worry too much if you go over it.

Whitespace

• Spaces are to be used for the formatting of code or text which does NOT effect the flow of the program. This includes arguments, docstrings, and the like. This is to ensure that tab sizes don't effect the visual alignment of elements.
• Be conservative with whitespace. Prefer funcname(arg1, arg2) over any of the additional whitespace in funcname ( arg1, arg2 )
• Use whitespace to lend some clarity to mathematical statements. Prefer 1 + 2*3 over 1 + 2 * 3. Though it may seem excessive in this example, in more complex equations it can greatly help readability.
• If unsure about the above, or when equations are massive, use parenthesis.

Blank Lines

• No particular guideline as yet. Prefer one line between functions, and two between classes.
• Should not be more than two.

Imports

• All imports should be at the top of the file.
  • What about imports which are clearly part of a self-contained function? What about people messing with dir()?
  • I don't give a shit if it's self-contained. It's just yucky.
  • If people are messing with dir(), just let them. They clearly want to get in there to do shit.
  • The only valid argument I'll accept is "It's required to avoid import loops", though at which point you should really consider refactoring it such that such measures are not required.
• One import per line.
• If using a from import, multiple imports are permitted (from x import y, z)
• Avoid using a from import unless it makes code clearly cleaner. Prefer math.sqrt(x) over sqrt(x). Prefer BeautifulSoup(string) over bs4.BeautifulSoup(string).

Comments

• If there is a section of code (longer than 4 lines) which does something not immediately obvious, give it a simple one-line comment.
• If there is a longer section of code which does something non-obvious, and you can't break it up into smaller segments, rewrite it and follow the above rule. We don't accept spaghetti code.
• All regex must have a comment preceding them explaining what the regex matches or searches for.
• If you use regex inline comments, murder happens. So much murder. Like, "whole family massacre" sort of deal. Or even plausibly mass extinction. Point is, this ain't Perl.

Block Comments

• Block comments should be made up of inline comments. These comments are only recommended at the top of a file, describing the file.
• Avoid using them to describe complex sections of code. Complex sections of code should be refactored, not explained.

Inline Comments

• Try to keep these comments seperate from code. They should be placed above the relevant piece of code, not on the same line as that code.

Documentation Comments

• We recommend that you put all API and command documentation in the docstrings for each related block.
• If you need to document a strange method of solving a problem, rewrite it. We are not fans of strange solutions to simple problems in real projects. If you can't, use blocks of inline comments.

Naming Conventions

• Classes should be in UpperCamelCase at all times
• Functions and Methods should be lower_case_underscored
• Variables are also lower_case_underscored at all times.
• Unless absolutely necessary, packages should be a single word, in lowercase. Multiple words should be underscored.
• One letter variable names are to be discouraged at all times. The only exception is if the variable is not used (say in a for loop, where the iterator is just an unused counter).

Misc

• Arguments Discussion is ongoing