Document Your Code

Photo by Artur Shamsutdinov on Unsplash

Comments Take CPU Time

We’re on the verge of the Exascale Age, computers are quite good at parsing text, and the biggest challenge with software at scale is maintenance and onboarding.

What is a Good Comment

The classic paraphrase of “Describe your intent, not your logic.” is always helpful.

def unpack(results: dict) -> pollkit.QueryResult:
"""
Unpack provided results, typically coming from the
web API or data cache. There are a number of checks
done in this function, each of them documented below
with a "# Check: ..."
.. tip:: This will always force file-path fields into unix
style slashes. ``file://`` will also be stripped if
found.
:raise: :ref:`pollkit.QueryResult.Invalid`` if the
data isn't aligned. Best to use try/except for
anything that doesn't need to succeed.
:param results: ``dict``
:return: :ref:`pollkit.QueryResult`
"""
for key, val in results.items():
# ...

Action at a Distance

It’s typically helpful to relay connection information for events that are not obvious while reading.

# Note: This will trigger an update on the UI
# via the pollkit.add_connection(...)
pollkit.fetch_data()

Be Verbose (to a degree)

Describing, in detail, what something does, is rarely a bad thing.

Be Exact

  • Work on your terminology and stick to it while documenting.
  • Build a glossary for anything that’s specific to your code

Be Persistent

The biggest challenge is getting used to documenting nearly everything. It’s a constant battle between your desire to keep going on the project when you have a great idea and remembering that you may one day need to share the lines of code with others (or your future self).

Practice

That’s the best tool you have. Write simple APIs or applications and document the heck out of them. See if your peers can unpack that information and use it without your intervention.

Finally, Add Examples!

Examples are the single most useful tool for understanding code. Odds are, when looking at documentation, you scroll passed text blocks and look for MVP examples of some kind.

def unpack(results: dict) -> pollkit.QueryResult:
"""
...
.. code-block:: python raw = pollkit.fetch_data()
try:
results = unpack(raw)
except pollkit.QueryResult.Invalid as err:
interface.push_error(err)
else:
interface.merge_result(results)

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store