5.4. Style Guide

It’s important for a project to have a standardized style for it’s code. The King Phisher project, being a Python project follows the PEP-8 style guide with the following notable exceptions:

  • Do use hard tabs instead of spaces.

  • Do not use more than one consecutive blank line, ever.

  • Do limit lines of code to 120 characters long instead of 79.

    • Do limit documentation lines to 80 characters long.

  • Do use single quotes for strings with the exception of template strings (such as those used by str.format) and documentation strings which should use triple double-quotes.

  • Optionally use additional spaces within a line for visual grouping. For example, when defining a long list of constants use additional spaces after the name and before the value to align all the values on the right.

5.4.1. Multi Line Indentation

Use hanging indentation for parenthesized statements. This is to say, the last non-whitespace character of the line should be the opening parenthesis with each subsequent line being indented until the closing parenthesis. Furthermore, in the case that this style is used, each expression should be on a separate line.

Example:

# good (standard one-line invocation)
this_function(takes_two, different_arguments)

# good (multi-line invocation)
this_other_function_has_a_longer_name(
    and_also_takes_two,
    different_arguments
)

# bad
this_other_function_has_a_longer_name(and_one_argument_up_here,
    and_another_down_here
)

This same style is applied to multi-line list, tuple and dictionary definitions with the bracket, or curly-brace taking the place of the opening and closing parenthesis as appropriate.

5.4.2. Special Method Names

Some functions (and methods) have special prefixes or suffixes to denote specific compatibility. Prefixes are permitted to be either preceded by a single or double underscore to denote internal or private use respectively.

Name Type Details
_tsafe Suffix Non-Main GUI thread safe
async_rpc_cb_ Prefix An asynchronous client RPC callback
signal_ Prefix GTK signal handler

5.4.3. English Verbiage

Use full, complete and grammatically correct sentences for all documentation purposes. This includes class, function, attribute, and parameter documentation. Additionally, proper sentences should be used for any messages that are displayed to end users with the notable exception of log messages. Log messages are to be entirely lowercase with the exception of acronyms which are currently inconsistently cased. Either all capital letters or all lower case letters are acceptable for acronyms within log messages.

5.4.4. Documentation

When documenting a function, use the grammar provided by Sphinx. Documentation strings should be surrounded by triple double quotes ("""). There should be a single blank line between the body of the description and the parameter and return definitions.

def add_two_numbers(x, y):
    """
    Add two values specified as *x* and *y* together returning their sum.

    :param int x: The value for the first number to return.
    :param int y: The value for the second number to return.
    :return: The sum of the two values.
    :rtype: int
    """
    return x + y

Native Python types are able to be specified on the :param line. More complex types, such instances of classes defined by modules in the project must be defined on a separate line using a dedicated :type annotation. See the Sphinx documentation for the Python Domain.

:param foo: The widget this function uses.
:type foo: :py:class:`~the_full.module_path_to.Foo`

5.4.5. CLI Arguments

For utilities which take arguments on the command line, the following default values should be supported.

Argument Flag Meaning
-h / --help Display help information
-v / --version Display version information
-V / --verbose * Enable verbose output
-L / --log * Set the log level to use

* These values are optional, but should not be overridden.

5.4.6. Log Levels

When logging messages, the following levels should be used as described.

CRITICAL

Reserved for when an unrecoverable error has occurred that stops the application from running.

Examples:

  • A required library, module or resource file is missing.
  • An unknown exception occurs which is raised to the main method of an application.
ERROR

A recoverable error has occurred that stops the process from functioning as intended.

Examples:

  • On a client, the user fails to authenticate successfully.
  • A network socket failed to connect to a server.
WARNING

A recoverable error has occurred that does not stop the process from functioning as intended.

Examples:

  • On a server, a user fails to authenticate successfully.
  • When information provided by the user is invalid and the user can be prompted for new information.
INFO

High level information regarding what is happening in an application, should be use sparingly within loops.

Examples:

  • Listing resources that are being loaded and processed.
  • The child pid when fork() is used.
DEBUG

Low level information regarding what is happening in an application including the values of variables, this may be used more frequently within loops.

Examples:

  • Printing identifying information for threads that are spawned.
  • Printing the value of arguments that are passed into functions.