A good source code does not only works as smooth as silk on production, but should be well-documented and appropriately readable. This will be useful for all contributors including the creators themselves.

This blog we're gonna discuss about 2 simple stuff we can improve our source code to become a good self-explained source code.

Variable type annotation

This is for writing functions or program structures so that we can confidently control the variables flow. It's also called "Type hints", yes it's a hint for what type the variables there should be.

Type annotation is described on PEP (Python Enhancement Proposals) which is guideline to write Python in efficient ways.

Type annotation takes no effects on running a program but helps developers communicate to each other better on how to write good source code.

Let's say we are writing a function with arguments: num & text, those of them is easily recognized as an integer and a string, right? But what if there is an argument named unit? What type should it be? Probably an integer like unit means a number of unit, or it's possibly a string like "centimetre" or "boxes".

More example, we have an encryption function like this.

You can see arguments; text is definitely a string but what is offset? And what does this function return? Hmm, we need to declare something to make this function more readable. Like this.

When we start writing the function, IDE would show arguments needed and types like this.‌

And here are examples of annotating variable types.

Primitive types

Primitive types that is int, float, bool, and str are basic yet frequently used in daily life.

We add colon : after a variable followed by its types. Return type is defined after ->.

Default values

In some cases, we want to leave some arguments with default values. We give its value after =.

Choices of type

If we are using python 3.10 or newer, we can use pipe ( | ) express types that a argument could be.

With lower version of Python, we could use typing.Union module.

For more info about typing module, please follow the link below.

Collection types

When an argument is list, tuple, set, or other, we can define the collection type followed by bracket with its element type.

Control flow variables

Let's say we are adding a loop and we want to annotate a type to the iterator variable. We can't use : directly at the declaration. We need to declare it before the loop. After that we are now able to auto-complete attributes of the variable type.

In the same manner, unpacking is an easy shorthand method to extract a collection to individual variables. Yet we can't annotate at unpacking step, we need to do so beforehand.

I would credit this section to the stackoverflow comment here https://stackoverflow.com/a/41641489.

Docstring

Now comes to docstring. This docstring is like a helper we added to each function describing what this function does, what is its arguments, what does it return.

This is also defined in PEP.

I certained most of us are using modern IDEs such as my VSCode. Its intellisense greatly comforts coding time with auto-completion. So I would introduce a simple plugin for VSCode to generate a docstring and we are just filling the template, and it's done. This plugin is named "Docstring" straightforwardedly.