Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 21 additions & 13 deletions Coding-style-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,25 +18,33 @@ If you use [Sublime Text](http://www.sublimetext.com/), consider installing the


## Python

#### Black
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please move the section that talks about Black (basically, all the new stuff) just above the section that talks about Prettier, and give it the same level of heading. We should be consistent in how we describe the formatters.

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Have the Black hyperlink link to the section of this wiki page that discusses Black, instead.

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:

Expand Down