06. Python coding standards

Exemplar code

The following code is from our Ada Computer Science content page on the binary search algorithm (recursive), which includes a detailed explanation of the algorithm.

The exemplar code in the GitHub version also includes a main() procedure with test data and a call to binary_search_recursive().

def binary_search_recursive(items, search_item, first, last):
    """A recursive binary search algorithm"""

    # Base case for recursion: The recursion will stop when the
    # index of the first item is greater than the index of last
    if first > last:
        return -1 # Return -1 if the search item is not found

    # Recursively call the function
    else:
        # Find the midpoint position (in the middle of the range)
        midpoint = (first + last) // 2
        
        # Compare the item at the midpoint to the search item
        if items[midpoint] == search_item:
            # If the item has been found, return the midpoint position
            return midpoint
     
        # Check if the item at the midpoint is less than the search item 
        elif items[midpoint] < search_item:
            # Focus on the items after the midpoint
            first = midpoint + 1
            return binary_search_recursive(items, search_item, first, last)

        # Otherwise the item at the midpoint is greater than the search item
        else:
            # Focus on the items before the midpoint
            last = midpoint - 1 
            return binary_search_recursive(items, search_item, first, last)

Naming conventions

	Guidance (mainly based on PEP8)	Example
Variables/Parameters	Names in lowercase with underscores	user_name
Constants	Names in uppercase with underscores	LONDON_WEIGHTING
Functions/Methods	Names in lowercase with underscores	calculate_pay
Strings	Use double quotes
Characters	n/a
Classes	Class names are PascalCase	class UtilityVehicle

Spaces

• Code blocks - use 4 spaces per indentation level
• No space between function identifier and parameter list
• No space on function calls between function identifier and arguments
• Leave space on either side of operators
• Leave space after commas in lists
• Use white space (single line) if it helps readability
• Two lines between functions (or methods)

Comments

• Single line docstring (triple quoted) with important information
• In-line comments: 2 spaces before # and 1 after
• All comments: Capital letter at start and no full stop

String formatting

Use f-strings, e.g.

print(f"The sum of 1 to {n} is {result}")

Import statements

• Position import statements at the top of the module (below licence info)
• If a single function is needed, use a specific import, e.g. from math import randint. Otherwise import whole module, e.g. import math (and then prefix all functions with the name of the module, e.g. math.randint.

Main function

• On the platform do not use if __name__ == "__main__": (unless needed to meet a learning objective).

• On GitHub, always use if __name__ == "__main__":. The statements that follow should call a function named main (or another sensibly named function) or occasionally provide initial code to be executed when a module is run.

• When if __name__ == "__main__": is used, this comment should always be added immediately before the statement:

# This code will run if this file is executed directly
# i.e. not called by another program
if __name__ == "__main__":
    ### CODE TO RUN GOES HERE ###

Comment for top of GitHub file

# Raspberry Pi Foundation
# Developed as part of Ada Computer Science
# 
# Usage licensed under CC BY-NC-SA 4.0