0

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.

  • From my experience, I usually document a function with docstrings, but if you are looking to document a variable, you could use the `#` in row succession until you have it documented. I would refer to https://www.python.org/dev/peps/pep-0008/#comments – Scratch'N'Purr Dec 15 '16 at 12:06
  • http://effbot.org/zone/pythondoc.htm – mplungjan Dec 15 '16 at 12:07

3 Answers3

2

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.

A. N. Other
  • 392
  • 4
  • 14
  • What if i need document the type of the variable? –  Dec 15 '16 at 12:14
  • 1
    When writing a inline comment remember to put at least two spaces in front of the `#`. – J. P. Petersen Dec 15 '16 at 12:17
  • I think the following questions and answers will help you - http://stackoverflow.com/questions/7690220/how-to-document-python-function-parameter-types and http://stackoverflow.com/questions/3051241/how-to-document-class-attributes-in-python – A. N. Other Dec 15 '16 at 12:35
1

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 = ...
Nurjan
  • 5,889
  • 5
  • 34
  • 54
-1

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.

Vasili Syrakis
  • 9,321
  • 1
  • 39
  • 56