89 lines
4.7 KiB
Markdown
89 lines
4.7 KiB
Markdown
|
# How to create a class for the Central Data Model
|
|||
|
|
|||
|
This document explains the steps to follow if you want to contribute to the city data model by adding new classes or new attributes.
|
|||
|
Use this document after having a clear idea of how your data model should look like already integrated in the Central Data Model.
|
|||
|
Please, refer to the cerclibs.pdf (https://liveconcordia.sharepoint.com/:b:/s/CERC-Next-GenCities-Platform/EfPNAGXexCFOju2sKBr6pNMBcwnvLin1Wio1Ahpfu4cxag?e=rhkdca)
|
|||
|
to integrate your data model with the Central Data Model.
|
|||
|
|
|||
|
## Starting with the basics
|
|||
|
- Install all requirements and download the Libs project. [Here](WINDOWS_INSTALL.md) how to do it for windows.
|
|||
|
In order to maintain a good quality code, we will work in branches. New codes will need to pass quality standards before being accepted in the main branch.
|
|||
|
- Check and follow our [coding style](PYGUIDE.md)
|
|||
|
- Don’t forget to create unit tests and ensure that the old ones pass normally after your changes.
|
|||
|
- Imperative! Document your work using comments in the code and, if needed, adding text files with extended explanations.
|
|||
|
|
|||
|
If the code doesn't pass the quality review, it will be rejected.
|
|||
|
|
|||
|
## Adding new parameters to existing classes
|
|||
|
|
|||
|
Adding a new parameter is an easy task. Open the desired class, for example, CityObject:
|
|||
|
![city object](./docs/img_contributing/img_5.png)
|
|||
|
|
|||
|
Add the name of your new parameter to the list at the constructor and initialize it as desired:
|
|||
|
![new parameter](./docs/img_contributing/img_6.png)
|
|||
|
|
|||
|
At the end of the class, add the corresponding getter and setter. It is very important that they are documented!
|
|||
|
![getter and setter](./docs/img_contributing/img_7.png)
|
|||
|
|
|||
|
You will see that the name of the file (city_object.py) changes from white to blue. That means that your version is different
|
|||
|
from that one in the git. Once you finish doing your changes, you should commit and push them to your branch. The name of the file will turn back white.
|
|||
|
|
|||
|
## Creating a new class
|
|||
|
|
|||
|
Create a new class in the corresponding folder (if it does not exist, create a new folder ad hoc).
|
|||
|
![new folder](./docs/img_contributing/img_0.png)
|
|||
|
![new file](./docs/img_contributing/img_1.png)
|
|||
|
![add to git](./docs/img_contributing/img_2.png)
|
|||
|
|
|||
|
And add it to git (the name of the file will turn from red to green).
|
|||
|
Every new class must have:
|
|||
|
- A header with the following information:
|
|||
|
|
|||
|
```python
|
|||
|
|
|||
|
"""
|
|||
|
My New Data Class module
|
|||
|
SPDX - License - Identifier: LGPL - 3.0 - or -later
|
|||
|
Copyright © 2022 Concordia CERC group
|
|||
|
Project Coder Name of Project Coder name.project.coder@concordia.ca
|
|||
|
"""
|
|||
|
```
|
|||
|
|
|||
|
- A brief explanation of what it is, what it does, what it can be used for, etc. under its name:
|
|||
|
|
|||
|
```python
|
|||
|
|
|||
|
"""
|
|||
|
MyNewDataClass class
|
|||
|
This class models this and does that
|
|||
|
"""
|
|||
|
```
|
|||
|
|
|||
|
- All imported libraries together at the beginning.
|
|||
|
|
|||
|
![new class](./docs/img_contributing/img_3.png)
|
|||
|
|
|||
|
A data class contains properties that describe the data model. Therefore, it should be mainly composed by getters and setters.
|
|||
|
We would like to avoid having methods in the data classes. All those methods that could be done in the factories must be written there.
|
|||
|
The properties can be divided into two groups, those that can be modified during the use of the model, and those that
|
|||
|
are set only once and stay unchangeable. The line that divides these to groups is sometimes difficult to draw.
|
|||
|
An example to get a taste of this difference could be the following. A building is formed by surfaces, the list of surfaces
|
|||
|
is something that defines the building and, for our purposes, is unchangeable. On the other hand, if one of our studies is
|
|||
|
to show the effect of the construction on the building demand, we may want to modify this during the run, so the construction
|
|||
|
becomes changeable. This is important because those parameters that are static (unchangeable), must be provided for the
|
|||
|
initialization and don’t have setter, while the others are initialized at None and do have setter:
|
|||
|
|
|||
|
It is important to highlight that all setters and getters (@property) must have comments to describe the parameters, as shown in the previous image.
|
|||
|
|
|||
|
![new class getters and setters](./docs/img_contributing/img_4.png)
|
|||
|
|
|||
|
Once you finish doing your changes, you should commit and push them to your branch. The name of the new files will change from green to white.
|
|||
|
|
|||
|
## Documentation and authoring
|
|||
|
There can be two types of authors, that one who created the model and that one who coded it. If they are not the same person,
|
|||
|
in the headers of the classes must be just the name of the coder, who is the reference person to ask anything about the code,
|
|||
|
and the one in charge of maintaining it, and interacting with the git.
|
|||
|
|
|||
|
The author of the data model will appear in the official documentation of the Insel4Cities platform. In those documents,
|
|||
|
a larger explanation of the data model should be also added.
|