diff --git a/Coding-style-guide.md b/Coding-style-guide.md index f652223c..53f2d095 100644 --- a/Coding-style-guide.md +++ b/Coding-style-guide.md @@ -18,25 +18,33 @@ If you use [Sublime Text](http://www.sublimetext.com/), consider installing the ## Python + +#### Black +Oppia uses [Black](https://black.readthedocs.io/en/stable/) as the standard Python code formatter. +Black enforces a consistent, opinionated style automatically and is run as a pre-commit hook. + +- **Automatic formatting:** Black runs every time you make a commit to ensure consistent code style. +- **Manual formatting:** You can format a specific file manually using: + ```bash + black /home/dev/opensource/oppia/core/controllers/android.py + + - Consider using a frozenset or tuple to a list, if the data structure is not meant to be subsequently modified. This applies especially to constants. - If you need to raise an Exception, just do `raise Exception` -- no need to define custom exceptions. We tend to use exceptions fairly sparingly, though. - Otherwise, please follow the [Google Python style guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md). In particular: - There should be two empty lines before any top-level class or function definition. - It's OK for the initial documentation string to be more than one line long. - Prefer string interpolation over concatenation -- e.g. prefer: `'My string %s' % varname` to `'My string ' + varname`. - - When indenting from an open parenthesis ('('), prefer indenting by 4 rather than indenting from the position of the parenthesis. e.g., prefer: - - ``` - my_function_with_a_really_long_name( - 'abc', 'def', None) - ``` - - over - - ``` - my_function_with_a_really_long_name('abc', - 'def', - None) + - **Indentation inside parentheses:** + Let [Black](https://black.readthedocs.io/en/stable/) handle indentation and line breaks automatically. + Do **not** manually align to the opening parenthesis or indent by a fixed number of spaces. + For example, Black will format code like this: + ```python + my_function_with_a_really_long_name( + "abc", + "def", + None, + ) ``` - Docstrings should start with """ and end with """. The content of each docstring should be left-aligned. For example: