Organization and Documentation¶
Projects, and especially engineering projects need good organization and good documentation. We learned earlier about Git and GitHub and this can help us to organize our project (especially code). But, we also need to document. We can document in a few different methods.
- Comments in code
- Markdown/Text files
- LaTeX
Markdown and text files¶
A simple text file can help to convey a lot of information. This is typically contained in a file called readme.txt. With GitHub, a more common file is readme.md which is a Markdown file. The reason for this is that GitHub will automatically render these.
Markdown files offer the simplicity of text but also can add some additional features such as italics, bold, underline, web links, and even lists and tables.
Readme!¶
Why Readme? Readme files have been used almost since we have been programming. The idea is simple, read the file! Readme files often contain important information such as installation, requirements, how to use it, and other information that usually should be read first before using the program.
Can you use other filenames? Absolutely, but readme.* is fairly universal in what it does.
Code Comments¶
Comments¶
It's easy to point out the obvious when commenting on your code, but a better approach is to describe what you are doing or at least attempting to do. But, let's start with some basics, how do we comment in Python
# This will comment a single line
print('This line will be executed.')
'''
This is a block of code. Here we can write
a large amount of text. This is useful for
documenting functions.
'''
This line will be executed.
'\nThis is a block of code. Here we can write\na large amount of text. This is useful for \ndocumenting functions.\n'
There is more to using the single quotes (and why Jupyter notebook treats it different). Those are usually referred to as a "docstring". As you might imagine, they have the purpose of...documenting. If we look at the function below, while it is a simple function, we may not know exactly what is going on.
import math
_SQRT_5 = math.sqrt(5)
_PHI = (1 + _SQRT_5) / 2
def approx_fib(n):
return round(_PHI**(n+1) / _SQRT_5)
Let's improve this and add some documentation. The format below is the Google style. This is a fairly simple method which is fine. Comments do not need to be overly complicated. The intent is that you can read the comments and be able to understand how the code or function works.
def approx_fib(n):
'''
Approximate Fibonacci sequence
Args:
n (int): The place in Fibonacci sequence to approximate
Returns:
float: The approximate value in Fibonacci sequence
'''
return round(_PHI**(n+1) / _SQRT_5)
One advantage of docstrings is that most modern IDEs can take advantage of them and present you with documentation as you are typing or hovering over the function.
By the way, the format above is the Google style. This is a fairly simple method which is fine. Comments do not need to be overly complicated. The intent is that you can read the comments and be able to understand how the code or function works. Let's look at another example.
def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
"""Example function with PEP 484 type annotations.
The return type must be duplicated in the docstring to comply
with the NumPy docstring style.
Parameters
----------
param1
The first parameter.
param2
The second parameter.
Returns
-------
bool
True if successful, False otherwise.
"""
Sphinx¶
So why would we want to take extra time to make our code comments look like this? The answer is that we can use our comments to autogenerate documentation. One program that is often called Sphinx. Sphinx can parse our code for comments and use that to build up documentation.
Sphinx also uses another type of lightweight markup language called ReStructeredText (ReST or RST). RST, like Markdown, is designed to use minimal text to format text. With this, we can put RST in our comments and Sphinx will render it as such.
Demo on how this works in the Homework¶
Next time, we will discuss $\LaTeX$.