5 Things to Keep an Eye on for Proper Python Code Documentation

Before you started a career as a software developer, you probably thought that the entire job would be writing and testing code. But now you know better. It turns out that, actually, that’s only half the job.

The other half is ensuring that other developers, and internal and external stakeholders, know how to properly use and maintain your code. That’s where documentation comes in.

We’re going to take a look at what code documentation is, why it’s important to write good documentation, and five of the key things to remember that will help you do just that.

What Is Code Documentation?

Documentation is an incredibly important part of software development, regardless of which programming language you’re writing it in. Simply put, it is the process through which code is documented by software programmers.

Code documentation will consist of comprehensive explanations and clear illustrations of what your codebase does, and how it should be used. Code can be documented with automatic tools, but using solely this method will often result in under-documentation.

Why Is It Important to Write Documentation?

Guido van Rossum, author of the Python programming language, famously stated that;

‘Code is more often read than written’.

This quote alone highlights why code documentation is so important.

Code documentation is carried out for the benefit of two key audiences; users and developers. Extensive, comprehensive documentation will enable both groups to use and maintain the code without as much need for your support, meaning they are more productive, and so are you.

Good documentation will save more time later on than it takes to write now. If you’re coding a project that is to be open source, good documentation will attract developers to the project, as it will be much easier for them to get to grips with and contribute to it.

Want More Tech News? Subscribe to ComputingEdge Newsletter Today!

5 Things to Remember for Proper Python Code Documentation

When undertaking Python code documentation, there are five key things to remember that will make the process as painless as possible for you, and for those who come to read your documentation in the future.

1. Structure

Daniele Procida, Director of Engineering at Canonical, and avid Python programmer, proposes that documentation should be split into four categories, each with a specific goal to achieve.

Tutorials

Tutorials provide an entry point to your code, introducing a developer to the capabilities of your code, and preparing them to develop on top of what you’ve already written. By the end of the tutorial section, a developer should be ready to start working autonomously with the code you’ve written.

Tutorials should be brief, yet contain all the key information necessary for someone to understand your project. They should be easy to follow, but not so easy that you risk over-explaining every detail, as this will provide excessive distractions for the learner.

How-To Guides

How-to guides will be step-by-step instructions on how to solve specific problems that they may encounter. They should be focused and relevant, and yet may be more abstract than a tutorial, allowing the user some flexibility in how they tackle slightly different challenges.

Whereas tutorials are an introduction to the ‘rules’ of your project, how-to guides are tools to assist users in answering questions they may have, for example, “Is it appropriate to make use of a Parquet file in this project?”

Explanations

Explanations are designed to provide clarity on particular topics. They give you a chance to expand upon the why of your code, which will have been largely absent from the tutorial and how-to sections for the sake of brevity.

Different approaches and examples can be included here, and connections can be made between disparate elements of your project. Explanations are one of the most commonly overlooked aspects of documentation.

Reference

The reference section will contain precise, structured, and descriptive information on how to use a particular method, class, or function. It should be dictionary-like in its explanations.

2. Other Inclusions

There are several other boxes you should endeavor to tick when documenting your code, whether you’re using Python to build a website, or coding for big data within the Hadoop Ecosystem.

License

You should include a plaintext file that includes the license used by your project. This informs the user on whether the project is free to be used commercially and to what extent. This is especially important for open-source projects.

Collaboration

For open-source projects, including a collaboration section will inform users about how you expect new collaborators to contribute to the project. This could be fixing bugs, developing new features, reporting issues, or even adding further documentation.

Framework Reusability

This will make users aware of what aspects of the framework you have built can be reused in order to save time, including data cross-validation script, data preprocessing pipeline, etc.

3. Comments vs. Documentation

Commenting is designed to help developers to understand the purpose and design of your source code.

Documenting, on the other hand, is designed to describe the use and functionality of your code. Documentation is designed primarily for users, whereas comments are intended for developers.

Commenting happens alongside your code, while documenting is done in docstrings. Finally, and most importantly, comments are helpful, but are not required. Documentation is vital, and should never be absent.

4. Docstrings

A Python documentation string, or docstring, allows you to embed documentation directly into your source code. They can provide substantial information about a method near to its definition, with the drawback that the source code can become somewhat cluttered with text.

In order to combat this, plugins are available which can hide docstrings until they are required. There are three widely accepted docstring formats; reStructuredText Python’s official docstrings, Google docstrings, and Numpy docstrings. You should remain consistent with your choice of docstring format throughout a project.

5. Utilizing Sphinx

Sphinx is a tool which will convert the docstrings of your project into HTML and CSS, so they can be presented to your users. It’s a tool written in Python which has a number of easily accessible built-in and third party extensions.

Document Your Python Projects

Writing good Python code documentation is incredibly important, for your users, fellow developers, and yourself. Write comprehensive documentation that teaches others how to use your source code, answers any questions they have regarding it, and instructs them where to add to it if necessary.

Get to grips with docstrings and the various ways in which your documentation can be displayed. Make use of tools, such as Sphinx, to help make the documentation process more efficient. Getting into the habit of writing good documentation will benefit you, your teams, and your business as a whole.

About the Author

Pohan Lin is the Senior Web Marketing and Localizations Manager at Databricks, a global Data and AI provider connecting the features of data warehouses and data lakes to create lakehouse. With over 18 years of experience in web marketing, online, SaaS business, and ecommerce growth. Pohan is passionate about innovation and is dedicated to communicating the significant impact data has in marketing. Pohan Lin also published articles for domains such as WebSitePulse and PingPlotter.