Coding norms

Drew Leske

Where the Software Development Guidelines are about the practice of developing software, this document is about details of implementation in all or specific environments.

General

The first rule of style in any programming environment is to start with community norms and build on those.

Comments

First, above all other rules about comments, comment your code. Get the comment down and then worry about the rest.

Comments should follow the prevaling style of the language, environment, or particular code base.

For shorter comments, appearing on a single line, informal partial sentences are typically used:

# do the thing
do_the_thing()

Longer comments typically describe a process and may cover several blocks of code. These generally use full sentences with regular capitalization and punctuation:

# The following section first gathers the flurbs but must sort them into the
# zmort before doing the thing.  The zmort will hold the original flurbs and
# also the converted flarbs.

# get the flurbs
flurbs = get_the_flurbs()
...

Of course, these types of comments often indicate code can be pulled out into a dedicated function.

Python

Pylint

Use pylint for all Python source files: every Python file in the project should contain, at minimum, the following header:

# pylint:

This line may follow the module docstring but should precede any other code.

Exemptions: Sometimes Pylint perceives a fault and we don’t agree. There are multiple places to declare an exemption:

• to declare an arbitrary block of code, such as a single line, exempt from a particular rule, it must be preceded by a directive to disable the check, and then succeeded by a directive re-enabling it
• to declare a function or method exempt, declare the exemption directly after the function declaration and docstring
• an entire module may be declared exempt by placing the exemption directly before the module docstring (typically the first line)
• an exemption may be defined for an entire project by describing it in .pylintrc.

With proper decomposition it is usually preferable to define an exemption at the method or function level (defining an exemption for a single line or block of code is tedious and adds noise to the code comments, while a project-wide exemption is generally too broad).

Exemptions are declared in a comma-separate list, following the marker disable=, except for in .pylintrc. Wherever defined, they must be documented except in trivial cases. Except in .pylintrc, these explanations immediately follow the exemption declarations.

def do_the_thing():
    """ Does that thing
    """
    # pylint: disable=too-many-statements,too-many-locals
    # - this is a lengthy procedure and it doesn't make sense to break it up
    # - the local variables are necessary for the length valdidation process
    ...

Single, double and triple quotes

Use single quotes for simple strings, such as single characters or string literals used as index keys.

Use double quotes for text and for complex strings where there are substitutions, format markers, or other operations.

Examples:

# index key
print(message['greeting'])

# single character
if choice == 'q':
    # text
    print("Goodbye")
else:
    # complex string
    print(f"Did not understand: {choice}")

print("I was leaving anyway")

Use triple quotes sparingly, apart from for docstrings: they break up the indentation flow of the code and slow scanning. For some use cases, such as informative user messages or SQL query strings, these are best defined as constants and located in their own section, typically at the top of the file.

Docstrings

(These norms specifically apply to the use of triple-quoted strings for in-source documentation.)

First, document all public classes, methods, functions, and structures with docstrings.

Docstrings of a single line may be expressed with the opening triple quote on the same line as the content, followed by the closing triple quote on its own line:

def do_the_thing():
    """ This is is a simple function like the others.
    """
    ...

Docstrings of multiple lines should be expressed with the triple quotes on their own lines:

def do_the_complex_thing(arg1, arg2):
    """
    This complex function takes several arguments, does a specific thing or
    series of things which is or are briefly explained by this text, and then
    returns a result, also explained here.  How much detail is up to you.
    """
    ...

In both cases, the docstring is clearly demarcated from the first lines of code by the closing triple quote.

Arguments, return value and notes may also be described where useful:

def do_the_complex_thing(arg1, arg2):
    """
    (...all that stuff from before...)

    Args:
    - arg1: something about arg1
    - arg2: something about arg2

    Returns: A dictionary of information you should have.

    Notes:
    - inspired by https://stackoverflow/article/30493094
    """
    ...

The level of detail required depends on visibility of the entity and of the project overall–a public class in a public package must be documented, or it should stay private; a public class in a private package should be documented as the team will need this; a private class may be considered to be sufficiently obvious.

So, consider the audience and their needs.

Nested functions

Python allows functions to be defined within other functions. These are called nested functions. We use nested functions to keep helper functions in scope of a larger function and make such a function more readable. This also avoids unnecessary clutter in the outer function’s namespace.

def outer():
    """
    This is the outer function
    """
    def inner():
        """
        This function is defined within outer() function
        and only usable within outer() function
        """
        print("I'm an inner function")

    inner()

We’ve established the following rules for the use of Python nested functions:

1. There can only be at most one level of function nesting. This means that inner functions cannot have another function defined within them.

2. An outer function (meaning that function is not defined within another function) can have multiple inner functions defined within it.

3. All of the inner functions must be defined at the top of the outer function.

4. A recommendation, not a rule: Inner functions should take parameters rather than directly manipulate variables of the outer scope.

---