Good code vs bad code: why writing good code matters, and how to do it
When writing code in any language, there are good coding practices — and there are really bad ones.
Both may be correct as far as compiling and when they’re run. But bad code can present some problems in development, debugging, and modifying. In the workplace, no matter how well your program runs, someone will have to read and/or alter your code at some point.
They may have to add new features, correct a rare bug, or they might just want to read it to understand how it works. Similarly, you will have to read someone else’s code to do the same thing. Everyone will get along a whole lot better if the code is readable and understandable.
To know the importance of good quality code, let’s try to understand what a bad quality of code can lead to. Badly written code could lead to financial losses or waste of time needed for further maintenance, enhancements or adjustments to a software.
You write your code once, but then follow it numerous times after. Hence, documenting your code becomes really important, and naming conventions become really important.
Many times I come across my colleagues joking about how they do not remember what code or logic they wrote a few days ago. Now couple it with writing bad code style, and you will take more time to understand what you did. Things start to go haywire when an artist fails to understand their own piece of art 🙃🙂🙃
Key points to keep in mind while writing code
// Comments to the rescue
Most modern languages have declarative documented comments, and their use in conjunction with single and multi-line comments makes code more understandable — and hence maintainable.
Good code comments explain why things are done, not what is done. The code itself explains what is done. The need for comments should be minimal.
Good code is properly structured as shown in the figure. It should be obvious for the person trying to understand code where a block of code starts and where it ends, so that following the logic of the code base becomes evident and straight forward.
It is annoying when you have a project’s code base in front of you, but setup and first execution takes hours to get you rolling. This is where readme’s come in handy.
It is always better to have a brief intro to a project before you access the code, and a properly structured Readme does exactly that. A properly structured Readme looks like the below:
Many times we come across a Class by the name
Apimanager, but looking at the name, the purpose of class is not clear.
According to best coding practice norms, our classes should follow single responsibility principle (SRP). Proper naming conventions coupled with SRP makes our lives much easier while trying to follow a project.
Naming conventions should also vary for different scopes if a Class is performing some intensive unit of work. This is in order to differentiate when and where a variable becomes out of scope just by looking at the block of code.
Use meaningful naming conventions for all but the most transient of objects. The name of something is informative about when and how to use the object.
Avoid magic numbers
What is a magic number? It is a constant, completely undocumented, that must be a particular value for the program to work correctly. No one knows why that number was chosen.
At its most magical, no one really knows how the number affects the program… other than that changing it breaks things.
Magic numbers are evil and should be abolished on sight.
Adjusting to timeframe
The picture below speaks for itself.
Common practices for writing clean, good quality code
Writing good quality code is a dynamic process. Some more points to consider while trying to write “good code”:
- Good code is well-organized. Data and operations in classes fit together. There aren’t extraneous dependencies between classes. It does not look like “spaghetti”.
- Good code is well-tested. Tests serve as an executable specification of the code and examples of its use.
- Good code is not “clever”. It does things in straightforward, obvious ways.
- Good code is developed in small, easy to read units of computation. These units are reused throughout the code.
Thanks for reading, please share it if you found it useful :)