What exactly is “clean code”? Generally speaking, clean code is code that is easy to understand and easy to change or maintain.
As code is more often read than written, practice writing clean code is crucial in our day to day client projects.
Today, I am sharing some tips that I have gathered over the years while also giving some examples in IPython.
With that said, these principles should generally apply to most programming languages.
- Be consistent when naming things
- Avoid room for confusion when naming things
- Avoid double negatives
- Write self-explanatory code
- Do not abuse comments
Be consistent with naming
Maintaining consistency throughout a project is crucial to avoid confusion and doubts. This applies to variable names, file names, function names, and even directory structures.
Nothing should be named solely based on your individual preferences. Always check what other people already wrote and discuss it before changing anything.
The print() is a built-in function that displays a message on the screen. In our case, it’ll show the message ‘Hello, Word!’.
If everything is fine, you’ll see the following message on the screen:
Write Self-Explanatory Code
In the past, I remember being told that modellers should sprinkle comments everywhere to “improve code quality.”
Those days are long gone. Instead, modellers need to write self-explanatory code that makes sense to people. For instance, we should try to capture a complicated piece of logic in a descriptive and self-reading variable.
A comment is text in a program’s code, script, or another file that is not meant to be seen by the user running the program. However, is seen when viewing the source code.
Comments help make code easier to understand by explaining what is happening and help prevent portions of a program from executing.
NOTE: Use comments where appropriate and don’t over do it.
Unlike other languages like C++, Java etc. IPython relies on space or tab indentation rather than brace specified code block. Each statement in IPython is preceded by a space, double space, or tab. You cannot use a tab at one place and a space on the other as the indentation needs to be consistent throughout the code. This tells Python that you are starting a new block of code. A few examples of IPython indentation are provided below:
There are a lot of unique ways to implement a specific task in Python. These are concise methods that help in shortening the code and make it look elegant. Let’s look at each of them one by one.
- List Comprehensions: It is a sophisticated way to create lists in a single line. Rather than explicitly using assignment inside a loop, we can create a list within square brackets with the loop defined inside. To read more about list comprehensions, must read: List Comprehensions in Python.
- Swapping Variables: When swapping variables in python, rather than using temporary variables and other weird ways (adding or dividing variables) you can do it in a single line of code. Example, to swap two variables, a and b: a, b = b, a. This is Python’s way of swapping variables!
- Slicing: It is used to carve out a specific part of a list or a string. It is super useful when you need to extract a smaller list or string from a larger one and can be implemented using a colon as a separator in between the initial and the final variables. You can even leave the start or the end value. To read more about slicing, must read: Slicing in Python.
How Do I Apply This Knowledge?
No one is capable of writing clean code from day one. As a matter of fact, everyone starts by writing “bad” or “ugly” code.
Like most things in life, to be good at something, you have to keep practicing over and over again. You have to put in the hours.
Besides practicing, here are the things that worked for me:
- Keep asking yourself questions like “Is there a better way of writing it? Is this confusing for others to read?”
- Take part in code reviews.
- Explore other well-written code bases. If you want some examples of well-written, clean, and Pythonic code, check out the Python requests library.
- Talk to people, discuss or exchange opinions, and you will learn a lot more.
Writing clean code is hard to explain to a lot of non-technical people because. For them, it seems to provide little to no immediate value to the business impact of the company.
Writing clean code also takes up a lot of extra time and attention, and these two factors translate to costs for businesses.
Yet, over a period of time, the effect of having clean code in a global script, custom action or .. is crucial for modellers(SAP CPQ role). With a cleaner code base, modellers will be able to deliver code and deploy applications faster to meet business objectives.
On top of that, having clean code is crucial so that new collaborators or contributors can hit the ground running faster as they start on a new project.