There are many resources that teach you how to write code, but when it comes to writing clean and readable code, many beginners are unaware of the principles and techniques. In this article we'll explore how to write Python headers, one of many things that can level up the readability of your code.

What are Python Headers?

In general, file headers are blocks of information - often positioned at the top of the file - that contain metadata about the file and its content.

Similar to this, a Python Header consists of a shebang and a docstring present at the top of the file that provides more information about the file and the code present inside it.

Why use Headers?

As mentioned, headers provide metadata about the file that can help understand the context as well as track the changes in the file. It not only helps the readers, but the developers to get up to speed quickly with the context.

What's a shebang?

You might see something like #! /user/bin/env python in Python scripts. The #! is referred to as the shebang. It is Unix feature of executable scripts and specifies the path of a valid executable.

You can specify the pathname to define a certain version of Python on the machine. Following are some examples

#! /usr/bin/env python
executes any python executable present on the machine.

#! /usr/bin/python
used in cases when python is installed in the /usr/bin directory.

#! /usr/bin/python2.7
used in cases to execute a specified version of the python executable.

#!python
works only if the python executable is present in the current directory.

What other metadata should I add?

Other than the shebang, there are a few more things you should add in your header.

Encoding

You can specify the encoding for the scripts. UTF-8 is the most commonly used encoding. Here's how you do it
-*-coding: utf-8 -*-

Docstrings

Docstrings are usually used to provide documentation or explanation about the important pieces of code. Explain the type of expected input values and what the piece of code does (usually functions).

You start with a short description about the file followed by the descriptions for the functions.

NOTE: Your code must only start after the docstring, else it won't be recognized.

Dunders

You can then add information about the author and other relevant information for the file using the following

__author__ = "Author Name"
__copyright__ = "Copyright Info"
__credits__ = ["Author", "Author"]
__license__ = "License Name and Info"
__version__ = "0.0.0"
__maintainer__ = "Author"
__email__ = "contact@email.com"
__status__ = "status of the file"

Now, you are not limited to these, you can use some of them or add more information. The reason we write the info this way is to access it.

What is a proper format?

Although there is no hard-defined format you should use, here's a frequently used format. You don't have to use all the prompts mentioned here strictly, feel free to add and remove metadata according to your use case, but keep the format similar and information relevant.

You can follow this format

1. Shebang
2. Encoding
3. Docstring
4. Dunders
5. Imports

Code Snippet: code

Python Things Repository: repo

Footnote

Hope you liked this small article and it helps you write better Python code. I plan fill this series with small articles about python concepts, tips, tricks, and tutorials.

You can find me here:
Twitter
Website