Good Code vs Bad Code

Why writing good code matters, and how to do it

Navdeep Singh
Jul 25, 2017 · 4 min read
Image for post
Image for post

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 are 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 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 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 which 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.

Indentation

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 straightforward.

Image for post
Image for post
Indentation: Regular norm four space indent

README’s

It is annoying when you have a project’s codebase in front of you, but set up 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:

Readme template, credits: PurpleBooth

Naming conventions

Many times, we come across a Class with 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 the single responsibility principle (SRP). Proper naming conventions, coupled with SRP, make our lives much easier while trying to follow a project.

Naming conventions should also vary for different scopes if a Class is performing an intensive unit of work. This is 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.

Image for post
Image for post
Code quality to deadlines

Common Practices for Writing Clean, Good Quality Code

Image for post
Image for post
Widely used steps to improve code quality

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.
Image for post
Image for post

Thanks for reading!

Better Programming

Advice for programmers.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store