Docstring

A well-written docstring should be clear, concise, and informative. It should explain what the function end goal is without being unnecessarily lengthy.

When writing docstrings, keep the following guidelines in mind:

• Be clear: The reader should be able to understand the function's purpose, inputs and outputs without needing to examine its implementation.
• Be concise: Avoid lengthy descriptions or unnecessary details. Focus on the purpose of the function.
• Mention all parameters: Include the names of all parameters and explain their roles when necessary.
• Specify exact return values: Clearly state what the function returns rather than vaguely describing what it determines.
  • When working with Boolean functions, explicitly mention when the function returns True and when it returns False.
  • Note that this only applies to functions that return a value. Not all functions will return a value, and in the case that nothing is returned, the docstring should still specify what the function does.

Assertions

Assertions are used to test whether a function produces the expected output in every scenario. Assertions should be accurate and clearly indicate what is being tested.

Note that not all assertions are tests. Some functions may include an assertion in their code to ensure that no unexpected value is being passed into the function (e.g. asserting that a value is positive). A test is written outside of a function, and is an assertion that checks if a function is behaving as we expect it to.

When writing assertions, keep the following guidelines in mind:

• Use descriptive assertion annotations: Every assertion must include a string, called an annotation, that clearly identifies what is being tested. Avoid generic messages such as “Test 1”, “Test 2” etc.
• Use a tolerance for floating-point values: If a function’s return type is float, its tests must use an appropriate tolerance rather than directly comparing floating-point values with == as you would for functions with return type int.
• Test a variety of cases: Although assignments may only require a couple assertions per function, this should be considered a minimum requirement rather than a limit on testing. Including typical inputs, edge cases, and other relevant scenarios helps to ensure the function behaves correctly in all cases.

General Style

Good coding style makes your code easier to read and understand. Even if your code produces the correct output, poor formatting can make it difficult for others to follow your logic.

Keep the following guidelines in mind:

• Use consistent naming conventions: Be consistent when naming variables and functions. Avoid switching between snake_case and camelCase throughout.
• Avoid conditional return True or return False: Excessive use of return True and return False can make code longer and more complicated than necessary. If a condition already evaluates to a Boolean value, consider returning the expression directly.
• Avoid == True and == False: When testing Boolean functions, use the function call directly or not to check for False.
• Use meaningful variable and function names: Variable and function names should clearly indicate their purpose. Avoid vague names such as x, a, b, foo, func, or temp when a more descriptive name would improve readability.
• Keep lines at a reasonable length: Avoid writing excessively long lines of code, including long expressions, assertions and docstrings.