Documentation in source code??? 🤯

[rating: beginner]

Triple quote text sequences are typically used for a special purpose, called a “docstring”, defined in Python PEP-257. Docstrings are used to provide documentation of packages, modules, classes & functions directly in source files.

In writing this post & from comments to my post on LinkedIn I realized there was a bit more to cover. So in the interests of keeping the newsletter short & digestible, this post focuses strictly on docstrings & next week will talk about more general documentation in your source code repository.

What’s the point?

One of the big challenges for developers is easily & quickly acquiring context about the code they are reading. If teams don’t take care of these cognitive load issues, then as a project grows in size it becomes increasingly difficult to maintain.

• Nobody can figure out where a piece of information should go.

• Nobody else can find that information.

• Synchronizing all the different versions of artifacts - documentation, source code, binaries, diagrams, etc - becomes it’s own complex task.

If businesses don’t take care of how this information is managed then it can become costly in terms of money & trust in the business itself.

• Production outages that take longer to resolve when someone wasn’t aware information existed & they had to reinvent the solution.

• Production outages that occur because someone was accessing the wrong information for the release they were using.

Docstrings are a really useful way to deliver a certain kind of documentation in a structured way directly adjacent to the source code it is addressing. Part of the utility is because it is a consistent format that means each code reviewer instinctively knows what to expect & how to read it - reducing cognitive load.

And because docstrings are right there with the source code in the source code repository, then it’s much easier to see that the documentation is correct, & understand when that documentation is in error.

Another important value of docstrings is that using tools such as sphinx other formats of documentation can be generated.

Need an offline & out of repo copy of documentation?

Maybe a pdf would be useful - generate that using Sphinx.

Want to put the documentation on a website of some kind for consumption by other stakeholders in the business?

Generate HTML using Sphinx & publish to your website location.

How do docstrings work?

When doing a little research about Python comments and character strings I realised that I thought of docstrings as comments, but they are technically character strings. And in fact they are character strings that behave a lot like comments - inert blocks of text distributed through the code.

def my_function():
	"""This function does a thing.
	
	Some more sentences. On what the function
	does, assumptions, or other information 
	relevant to a consumer of the function.
	"""
	pass

The reason this works is a quirk of Python & how it instantiates objects. Note that the following code is perfectly valid & runs clean - even if it does nothing useful. In many other languages this code would generate errors due to the unassigned data - the number 3.14 & the text "some inert text".

def my_function():
	"""My function demonstrating inert Python objects."""
	# an "inert" number
	3.14
	
	"some inert text"
	
	print("we did something!")

if __name__ == "__main__":
	my_function()

Docstring formats

There are several defined formats. For example, these are the docstring format choices available in PyCharm.

My preference is “Google” because it seems a bit more human readable to me. From this basic structured text, tools like sphinx can generate many formats for documentation.

def calculate_acceleration(velocity: float, duration: float) -> float:
	"""Calculate acceleration from velocity & duration.
	
  Args:
    velocity: Velocity in metres per second.
    duration: Duration in seconds.
	
  Returns:
    Calculated acceleration.
  Raises:
    RuntimeError: If velocity exceeds 10m/s.
 """
 pass

Even if you never generate any other format from your docstring documentation, it’s still a really useful documentation artifact right there in the file with your source code. A good IDE such as PyCharm can sometimes give you hints when docstrings are grossly misaligned with the source code.

References

https://peps.python.org/pep-0257/ - PEP-257 documentation

https://stackoverflow.com/a/24385103 - summary of docstring formats

https://www.sphinx-doc.org/en/master/ - Sphinx documentation

I'm Russell 🐿️. A long time engineer discovering new life as a first-time solopreneur.

I build software delivery systems using Docker & Python automation that increase speed & reduce errors - saving money & improving profitability.