Well-documented with variable type annotation & Docstring
2 simple stuff we can improve our source code to become a good self-explained source code.
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.
Examples
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.
Without type annotation
With type annotationAnd 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.
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 257.
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.
This plugin is easy to use. Just start typing """ and the submenu will popup.
Or using palette (cmd + shift + P) also works.
When we’re writing the function name, IDE would show this docstring and we will see the description of the function. Like this.
There are configurations for this plugin in Settings.
And there are also number of docstring formats we can pick.
All possible formats is exampled below: