Code review comment for lp:~javier.collado/utah/static_analysis_7

Revision history for this message
Javier Collado (javier.collado) wrote :

- Documentation strings

Note that not all strings are documentation strings, in particular (pep257: http://www.python.org/dev/peps/pep-0257/):
---
A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.
---

This means that strings literals in other locations are string objects that are constructed and then
thrown away. Those strings are the ones that should be marked as comments.

- Leading underscore in variable names

The general convention in python is to use a leading underscore to set private methods and
instance variables, that is, methods that are an implementation detail and shouldn't be accessed
from the outside (even if the language lets you do that).

Another general convention is to use a single underscore as a name for local variables
you don't care about and that can be safely discarded. An extension of that convention
(used by pylint, but maybe not widely adopted by the whole community) is to use variable names
with a leading underscore to state the same while providing a longer name that can be used
for documentation (when you see _stderr, it's clear that stderr is being discarded, when you see
just _, you have have to know the API or look at the documentation).

I don't find the two uses for the underscore confusing for variables because the scopes don't
mix together (instance variables vs. local variables).

« Back to merge proposal