As many programmers know, running code does not exactly mean good code. In addition to being executable, code also needs to be what is called “clean”, referring to code that is easy to read and understand.
In the article, How to Write Clean Code, Germán Cocca gives explains a large scope of what makes code clean. I have selected three areas that I found most beneficial to me as a CS student:
- Format and Syntax
- Conciseness and Clarity
- Documentation
Firstly, Format and syntax refer to how code is organized. Good format and syntax includes proper indentation, spacing, and variable naming that is consistent throughout the code. Furthermore, it is also important to make sure that variable names are meaningful so that its purpose is clear to the reader.
Secondly, It is good to be clear, but it is also important to keep it concise. Code that is too concise become difficult to understand because it sacrifices too many important details to minimize length. Code that is too detailed however becomes convoluted. Having clear and concise code makes it not only easier to read, but also easier to reuse, and so it is up to the programmer to know when to make the tradeoff between clarity and conciseness.
Thirdly, documentation cannot be understated. There is only so much information that can be expressed through the executable code itself, which is why clean code will always have comments that help guide the reader through what each part of the code is doing. That being said, it is important not to abuse the utilization of comments as this may affect the conciseness of the code. Therefore, comments should be used deliberately and formatted consistently.
Writing code requires a lot of planning and refining. Code will inevitably have to change and improve to meeting new requirements. Having clean code helps make this process more smooth and effective.
I learned this the hard way during my summer internship while using Jupyter Notebooks. Notebooks were especially useful because I was able to execute snip-bits of the code using its multi-cell functionality. However, this put me into a bad habit of not always using meaningful variable names or properly document what I was doing. And worst of all, I would often modify the notebook in ways that blurred the purpose of my code making it difficult to reuse later on.
After being set back a number of times, I realized my mistake and started fixing the way I would write my code. I started utilizing markdown and meaningful variables and would never delete or modify any of the finalized code I wrote, but instead make a new notebook or Python file with a new version noting why the new version was needed.
Poorly writing code may still compile, but it becomes very difficult to maintain. Writing clean code requires practice and awareness, but it is essential to making code easy to read and reusable.
Source: https://www.freecodecamp.org/news/how-to-write-clean-code/
From the blog Stories by Namson Nguyen on Medium by Namson Nguyen and used with permission of the author. All other rights reserved by the author.