152 lines
4.0 KiB
Markdown
152 lines
4.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 a word separator.
|
|
* Constant 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.
|
|
Place your imports 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 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
|
|
|
|
```
|
|
|
|
And like in the following example for read and write properties.
|
|
|
|
```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 through 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
|
|
|
|
```
|
|
|
|
### Coments.
|
|
|
|
#### Code documentation.
|
|
|
|
All public classes, properties, and methods must have code comments.
|
|
|
|
```python
|
|
|
|
class MyClass
|
|
"""
|
|
MyClass class perform models class operations
|
|
"""
|
|
|
|
def __init__(self):
|
|
|
|
|
|
@property
|
|
def object_attribute(self):
|
|
"""
|
|
My class object attributes
|
|
:return: int
|
|
"""
|
|
return self._object_attribute
|
|
|
|
def operation(self, first_param, second_param):
|
|
"""
|
|
multiplies object_attribute by two
|
|
:return: int
|
|
"""
|
|
return self.object_attribute * 2
|
|
|
|
```
|
|
|
|
Attributes with known units should be explicit in method's comment.
|
|
|
|
```python
|
|
|
|
@property
|
|
def distance(self):
|
|
"""
|
|
My class distance in meters
|
|
:return: float
|
|
"""
|
|
return self._distance
|
|
```
|
|
|
|
#### To do's.
|
|
|
|
Pending to implement operations should be indicated with ToDo comments to highlight the missing functionality.
|
|
|
|
```python
|
|
# ToDo: right now extracted at the city level, in the future should be extracted also at building level if exist
|
|
```
|
|
|