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:
|
||
|
||
|
||
Add the name of your new parameter to the list at the constructor and initialize it as desired:
|
||
|
||
|
||
At the end of the class, add the corresponding getter and setter. It is very important that they are documented!
|
||
|
||
|
||
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).
|
||
|
||
|
||
|
||
|
||
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.
|
||
|
||
|
||
|
||
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.
|
||
|
||
|
||
|
||
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.
|