If in the middle of my software, i have this variable that i need explain what it is and what is used for, i need document the variable.
I have a background in JS, so that's how i do:
/**
* Explain what the variable is, and what is for.
* @variable {Object} nameOfVariable
*/
var nameOfVariable = []
In the case of python:
# ??
name_of_variable = []
Is there conventions for this type of thing?
Thanks a lot.
Yes there is - this is what I can find
https://www.python.org/dev/peps/pep-0257/
For functions you can add a docstring e.g.
def some_function():
""" Write here a one line summary.
If wanted, then leave a line and write a more detailed one"""
The """ need to be indented correctly to work
However, for hashes #, which is more common after single variables, they don't need to be indented correctly. E.g.
some_variable = Something # This variable is doing this...
Hope that is somewhat helpful.
#.
PEP257 documents so called docstrings which is a string literal which appears as first statement in the definition of a module, class, function or a method. As far as I know if you want to leave some information about a variable you leave regular comments near it. For example:
# This is some variable ...
some_variable = ...
You might find that people document parameters, what a function returns, and so on, but usually variables are not documented in python libraries.
The names should generally be self-explanatory.
#in row succession until you have it documented. I would refer to python.org/dev/peps/pep-0008/#comments