Docstring comments are provided for every function (unless the assignment explicitly states otherwise)

Each function should include a docstring comment. The comment should include:

1. A short 1-2 sentence description of what the function does
2. Information about each parameter:
   1. The parameter name
   2. The data type
   3. Any assumptions about the parameters
3. An explanation of what the function returns, including the data type

I recommend and will use a style that is loosely based on google’s style. However, you may use any style as long as it includes the components listed above.

def sum_of_first_n(numbers, n):
    """
    return the sum of the first n numbers in a list that are greater than 0

    Args:
        numbers (List[float]): The list of numbers that we will use to compute the sum
            Assumptions: numbers includes at least n numbers that are greater than 0
        n (int): The number of numbers that should be included in the sum
            Assumptions: n >= 1

    Returns:
        float: the sum of the first n numbers in numbers that are > 0
    """
    # create list of numbers to keep that are > 0
    keep_numbers = []
    for number in numbers:
        if number > 0:
            keep_numbers.append(number)

    # get first n numbers
    first_n = keep_numbers[:n]

    # compute sum
    total = 0
    for number in first_n:
        total += number

    # return the final sum
    return total

Comments throughout code make code easier to understand for the reader

Comments in your code should make it easier for the reader to understand. Here’s and example of a reasonable number of descriptive comments:

def sum_of_first_n(numbers, n):
    """
    return the sum of the first n numbers in a list that are greater than 0

    Args:
        numbers (List[float]): The list of numbers that we will use to compute the sum
            Assumptions: numbers includes at least n numbers that are greater than 0
        n (int): The number of numbers that should be included in the sum
            Assumptions: n >= 1

    Returns:
        float: the sum of the first n numbers in numbers that are > 0
    """
    # create list of numbers to keep that are > 0
    keep_numbers = []
    for number in numbers:
        if number > 0:
            keep_numbers.append(number)

    # get first n numbers
    first_n = keep_numbers[:n]

    # compute sum
    total = 0
    for number in first_n:
        total += number

    # return the final sum
    return total

Do not comment every line - at some point, comments reduce readability, as you can see here:

def sum_of_first_n(numbers, n):
    """
    return the sum of the first n numbers in a list that are greater than 0

    Args:
        numbers (List[float]): The list of numbers that we will use to compute the sum
            Assumptions: numbers includes at least n numbers that are greater than 0
        n (int): The number of numbers that should be included in the sum
            Assumptions: n >= 1

    Returns:
        float: the sum of the first n numbers in numbers that are > 0
    """
    # create list of numbers to keep that are > 0
    keep_numbers = []
    # now loop through the numbers
    for number in numbers:
        # check if the number is greater than zero
        if number > 0:
            # append the number to the list if it is greater
            keep_numbers.append(number)

    # get first n numbers
    first_n = keep_numbers[:n]

    # compute sum
    total = 0
    # loop through the first n numbers
    for number in first_n:
        # add on to total
        total += number

    # return the final sum
    return total

I won’t give you an exact number, but comments every 3-5 lines tend to be reasonable.

Function, variable, and class names are descriptive

I could have written the function that I used in the other examples like this.

def my_function(xyz, qqqqqq):
    """
    return the sum of the first qqqqqq numbers in a list that are greater than 0

    Args:
        xyz (List[float]): The list of numbers that we will use to compute the sum
            Assumptions: xyz includes at least qqqqqq numbers that are greater than 0
        qqqqqq (int): The number of numbers that should be included in the sum
            Assumptions: qqqqqq >= 1

    Returns:
        float: the sum of the first qqqqqq numbers in numbers that are > 0
    """
    stuff = []
    for thingy in xyz:
        if thingy > 0:
            stuff.append(thingy)
    other_stuff = stuff[:qqqqqq]
    haha = 0
    for thingy in other_stuff:
        haha += thingy
    return haha

You’ll note that it’s a lot harder to understand what this function does when the variable names are random. Use descriptive variable names to make your code self-documenting.