Close

Code cleaning and documentation

A project log for Power Analyzer based on a COTS Power Monitoring IC

The idea of this project is the development of a power analyzer based on the ACS71020 power monitoring IC.

SebastianSebastian 07/09/2021 at 10:020 Comments

One of the most important things in any software program is readability. This does not only enable others to understand the program, but also decreases error-proneness.

As a first step, I reviewed how the code is structured.
Basically, all files are in one directory. The current structure is shown in the following diagram.

It is a simple structure. It consists of one page per general function. Because all of the pages look and function a bit different, it is not necessary to create an abstract base-class for pages. Utils can be used by all functions, while the serial_device ist instantiated by the backend.

One thing, that would make the GUI more intuitive would be to change the names of the pages. Something like "Values" seems to be more accurate instead of LivePage.

The names of variables should give a hint to what they do. While I'm at it, it is a good idea to make the page classes more consistent, too. They should all contain 

It is useful to add new pages later, in case the functionality should be extended.

Documentation

There are various documentation methods for python available. PyDoc uses docstrings (in triple quotes at the start of a method) and annotations in method signatures. More information can be found here.

All of that should increase the readability and extendability.

Apparently, I saved this as a draft...
The documentation of the code is finally done and a docs-folder now exists with the documentation to each python module, created with pydoc. It was interesting to learn about different documentation techniques, as there are many good solutions.

I used docstrings, because the project is kind of small and they were the easiest to do. For a bigger project, sphinx does look a lot more capable.

Discussions