Python Code Guidelines - Named Data Networking (NDN)

In addition to general guidelines in the C++, etc. Code Guidelines, the following guidelines apply specifically for Python implementations.

Filename conventions

File names should have all lower-case names, matching to the implemented class. If the class name is a composite of several words, each word in a file name should be separated with an underscore _ character. For example, the module implementing KeyLocator class should be named key_locator.py.

Combining implementations of different (related) classes in the same module is highly discouraged, unless the secondary class implementation is relatively short.

The goal of this naming pattern is to allow a reader to quickly navigate through the code base to locate the source file relevant to a specific type. Also, using lowercase names does not introduce unexpected errors for case insensitive filesystem.

Code layout

The code layout follows the general coding guidelines extended to Python. Do not use tabs for indentation. Indentation spacing is 4 spaces as outlined below:

def fooBar(test):
    if test:
        # do stuff here
        pass
    else:
        # do other stuff here
        pass

    for i in xrange(0, 100):
        # do loop
        pass

    while test:
        # do while

File layout and code organization

Each my_class.py module file should start with the comments shown below. The first line ensures that developers who use the Emacs editor will be able to indent your code correctly. The following lines ensure that your code has a BSD-style license, that the copyright holders are properly identified (typically, you or your employer), and that the actual author of the code is identified. If you are releasing the code under a different license, adjust the header appropriately. The final part is purely informational and we use it to try to track the most appropriate person to review a patch or fix a bug. Please do not add the “All Rights Reserved” phrase after the copyright statement.

Each module should contain a docstring that briefly describes the purpose of the module. The docstring may contain any information in reStructuredText format, which will be used for automated document generation. For more information about docstring, refer to PEP 257 – Docstring Conventions.

# -*- Mode:python; c-file-style:"gnu"; indent-tabs-mode:nil -*- */
#
# Copyright (C) YEAR Regents of the University of California.
# Author: MyName <my@email>
# See COPYING for copyright and distribution information.
#

"""
Describe the purpose of the module
"""

Comments

The project uses Sphinx Documentation Generator to document the interfaces, and uses docstring with reStructuredText content for improving the clarity of the code internally. All classes and public API methods should have docstring comments, for example:

class MessageError(Exception):
    """Base class for errors in the email package."""

def myMethod(self, value, optional = None):
    """
    Do something

    :param value: Value parameter
    :type value: str
    :param optional: Optional parameter
    :type optional: bool
    """

All parameters and return values for the public interface should be documented.

As for comments within the code, comments should be used to describe the intention or algorithmic overview where is it not immediately obvious from reading the code alone. There are no minimum comment requirements and small routines probably need no commenting at all, but it is hoped that many larger routines will have commenting to aid future maintainers. Please write complete English sentences and capitalize the first word unless a lower-case identifier begins the sentence. Two spaces after each sentence helps to make Emacs sentence commands work.

Variable declarations should have a short, one or two line comment describing the purpose of the variable, unless it is a local variable whose use is obvious from the context. The short comment should be on the same line as the variable declaration, unless it is too long in which case it should be on the preceding lines.

Miscellaneous items

Class private variables and methods should be prefixed with an underscore, according to Python convention.
The following Emacs mode line should be the first line in a file (or after the shebang line):
```
# -*- Mode:python; c-file-style:"gnu"; indent-tabs-mode:nil -*- */
```