Documenting the code
Student projects have a specific nature of short cadences and high personnel rotation, hence it is vital to remember about documenting your code properly, so that when another pack of students look at your code in the future, they can instantly understand what its general purpose is. To ensure that, we recommend documenting your code in following ways.
Each module, class and method should contain a docstring describing its purpose. Make sure not to simply repeat method's name, but explain its use in greater detail e.g. method create_generator should not have a description Create generator but rather Return a generator yielding numbers from a to b. Make sure to include parameters descriptions as well - they are the very first help you will look for when using a new method that you are not the author of (if you use PyCharm - ctrl+q). We will use reStructuredText docstring format as it is the most commonly used in Python. Please refer to PEP-257 for more detailed info.
Even though Python is a dynamically typed language, it is highly advised to include proper typing in your code. It limits the number of ambiguities connected to what the actual parameters should be. Imagine this example:
def set_pixel(coords):
self.pixel_x = coords[0]
self.pixel_y = coords[1]
When you are the author of this piece of code, you can probably guess what you should pass as coords, but will you remember it after a year? Will someone who looks at this code for the first time know it? Should it be a list or a tuple? Should it be an iterable of integers or floats? This is when typing comes in handy.
def set_pixel(coords: typing.Tuple[int, int]):
self.pixel_x = coords[0]
self.pixel_y = coords[1]
All clear now! It's obvious you have to pass a tuple of integers. You can also specify your custom typing objects:
from your_module import CustomClass
def cool_method(param: 'CustomClass'):
pass
If you only use CustomClass for type hinting, it is advised to import it using TYPE_CHECKING. This way, it will only be imported during checking type hints e.g. when running mypy and not when running the module itself. It will save you redundant module importing.
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from your_module import CustomClass
def cool_method(param: 'CustomClass'):
pass
Please refer to PEP-484 for more detailed info.
Proper variable naming can save a lot of time understanding what the purpose of your code is. Instead of naming variables as i, x or t1, give them longer descriptive names e.g. current_sample_gradient or EPOCHS_NUMBER. Please refer to PEP-8 for more detailed info.
Include all important user features of your code in README file. It is the first place that the user will be looking for when trying to use our code, so make sure that it is easily understandable for people not familiar with the project. Remember to use proper Markdown syntax!
Inline comments can be helpful to understand the reason for a particular complicated line of code. Please make sure to keep them succinct and a general rule of thumb is - don't explain your implementation but your intention.
Gradient PG - visit us!