What clean and modular code means, its importance, and some examples of best practices.
Clean and Modular Code
The main take home message of my last two weeks working on my GSoC_project can be summarized with a golden rule: write clean and modular code.
CLEAN: Readable, simple, and concise.
Clean code == Simple and clear != Redundant
Clean code is a characteristic of production quality code that is crucial for collaboration and maintainability in software development. Make it easy for the team to understand and maintain.
MODULAR: Logically broken up into functions and modules.
Modular code == Broken into functions and modules =! Entangled spaghetti
Modularity makes your code more organized, efficient, and reusable. This is something that may not be evident in your first experiences working on teams, but in the long run, it will pay off!
The importance of having clean and modular code can be summarized in three points. First, modular code means better readability because each function will be focused on one single purpose. Second, by having modules with a single purpose and function, we can reuse code more easily. And third, since it is easy to read, and to reuse, collaborating with members of your teams gets easier and faster, speeding up development time.
Other tips that I found useful to consider while working at the GSoC are summarized below.
Names of Variables
Provide descriptive names of variables. Long names are not necessarily meaningful names. A good rule of thumb is:
Descriptive variables + clear variable names –> no comments ✅
Arbitrary variables + unclear variable names –> needs comments ❌
- Avoid single letter names. Exceptions can be made based on the readers of your code when iterables are involved, but in general try to assign the best name to variables.
- Because python is untyped, specify the type of variable in the name if possible.
- Prefer list comprehensions over explicit lists when you can create a list from an iterable.
- Concise variable names can make code easier and more effective to read.
Concise names are easy to read and names may be even intuitive or common for other members of your team.
For example, when working with lipid bilayers, it is very common to identify
atoms by lipid type or by atom name. An effective way to ierate over items of
dict_lipids_ecoli would be
Each function should be focused on ONE thing. Avoid unnecessary side effects and keep it focused on one single task.
- A code smell is a function with more than 3 arguments. In many cases, using 3 arguments may be more effective, but a good rule of thumb to keep in mind is:
If the function has too many parameters, consider breaking into smaller functions
PEP8 provides guidelines on how to write code in Python. For example:
- Use whitespace properly, and use consistent indentation (4 spaces / indent).
- Line length should be shorter than 79 characters to keeping your code human readable.
Here an example of how select atoms using the MDAnalysis package following PEP8 guidelines
You can find more examples on code layout using PEP8 in here. For options to install Autopep8, this post may help. More useful cases for Atom selection using MDAnalysis are available in this tutorial.
In summary, the advantages of writing clean and modular code, in addition to best practices, will take you one step closer to a more readable code, which will be easier for your team to understand and maintain. Because simple code is better.