96 lines
3.0 KiB
Markdown
96 lines
3.0 KiB
Markdown
# Cerc Python Style Guide
|
|
## What's coding style and why it matters
|
|
|
|
Coding style is just how the code looks, it's incredibly personal, and everyone has their style.
|
|
|
|
Your preferred architectures, variable and function naming style all of then impacts in your code style and how the others read and understand it, so it could become a significant burden if everyone is coding on his own.
|
|
|
|
At CERC we are following the [PEP8](https://www.python.org/dev/peps/pep-0008/) with two spaces indentation instead of four.
|
|
|
|
## Tools.
|
|
|
|
We use [PyCharm](https://www.jetbrains.com/pycharm/) as an integrated development environment and follow the tool's overall advice but the space indentation, which we set to two spaces instead of default four spaces.
|
|
|
|
For code analysis, we enforce the usage of [pylint](https://www.pylint.org/) with our own [custom style definition](pylintrc)
|
|
|
|
## Naming convention
|
|
|
|
* Name your folders and files in lowercase.
|
|
* Your class names must start in capital letters and follow the python CapWords pattern.
|
|
* Methods and properties that return lists must end in "s".
|
|
* Methods and variables should be lowercase and use _ (underscore) as word separator.
|
|
* Constants names must be all capitals.
|
|
* Avoid the usage of "get_" and "set_" methods whenever possible, by using @property and @variable.setter decorators instead.
|
|
* "Private" methods, variables and properties start with _ (underscore)
|
|
|
|
## Imports
|
|
|
|
All the imports should be defined at the top of the file after the license and contact information comment
|
|
|
|
```python
|
|
"""
|
|
MyClass module
|
|
SPDX - License - Identifier: LGPL - 3.0 - or -later
|
|
Copyright © 2020 Project Author name name@concordia.ca
|
|
"""
|
|
|
|
import sys
|
|
```
|
|
|
|
Ensure that your imports are used and remove any unused.
|
|
|
|
|
|
## Object attributes and methods
|
|
|
|
Use properties whenever possible and encapsulate the access to all the calculated object attributes into a properties as shown in the following example.
|
|
|
|
```python
|
|
|
|
@property
|
|
def object_attribute(self):
|
|
if self._object_attribute is None:
|
|
self._object_attribute = ...
|
|
...
|
|
return self._object_attribute
|
|
|
|
```
|
|
|
|
or if the property can be modified like in the following example
|
|
|
|
```python
|
|
|
|
@property
|
|
def object_changeable_attribute(self):
|
|
return self._object_changeable_attribute
|
|
|
|
@object_changeable_attribute.setter
|
|
def object_changeable_attribute(self, value):
|
|
self._object_changeable_attribute = value
|
|
|
|
```
|
|
|
|
If your method or attribute returns a complex object use type hints as in this example
|
|
|
|
```python
|
|
|
|
@property
|
|
def complex_object(self) -> ComplexObject:
|
|
return self._object_changeable_attribute
|
|
|
|
def new_complex_object(self, first_param, second_param) -> ComplexObject:
|
|
return ComplexObject(first_param, second_param, self.property)
|
|
|
|
```
|
|
|
|
always access your variable throught the method and avoid to access directly.
|
|
|
|
```python
|
|
|
|
@property
|
|
def object_attribute(self):
|
|
return self._object_attribute
|
|
|
|
def operation(self, first_param, second_param):
|
|
return self.object_attribute * 2
|
|
|
|
``` |