Writing quality code

Felix Magani
5 min readFeb 11, 2019

--

As you continue with your quest of becoming the ultimate programmer, there comes a point where just writing code will not be enough for you. You will want write something more manageable, more correct, more portable and more clean. While this is a non-exhaustive list, it is a great point to start learning how to do all that.

1. Write Orthogonal code

When two things are orthogonal, a change in one thing does not affect the other. When writing your code always remember to reduce the interdependence between the various modules. Avoid global variables and always keep your code decoupled.
The benefits of this are:

  • Increased portability
  • You code becomes easier to test
  • There is less risk when changing any part of your system

2. Deal with all exceptions

Don’t leave any catch clause empty. Always write a code for each event that can happen. Leaving this out might be a very serious source of bugs in your system. Generic exceptions should also be avoided as much as possible, always catch specific exceptions. If you can’t handle an exception sometimes its even better to re-throw it back to the caller.

3. Functions should do only one thing

Functions should be short and should do only one specific thing which should actually be used to name the function. If you realize that your function is actually doing more than one thing, it might be a good idea to divide it to the various parts. This makes your code more readable and easier to test and debug.

4. Be consistent

If the framework you are building for uses some code styles, please stick to them and apply the style all over your code base. If you decide to name variables and functions in a specific way, also stick to that. This is actually so important when you are collaborating with other developers as people will easily infer a lot of things from the existing code and this will result to less confusion and increased familiarity.

5. DRY — Don’t Repeat Yourself

Duplication is the root of all evil in software. Imagine you had repeated the same URL four times in your code. This would require that you update all the four variables in case the URL changes. This is also a chance for an error to creep in if in any case you missed to change any of the four variables. This is just a simple example, sometimes it can be very critical and that’s why many principles and practices have been created for the purpose of controlling or eliminating it

6. Use code comments gracefully

Nothing can be so helpful as well documented comments. You should always keep your comments as updated as possible. Here are some important tips for writing good comments.

  • Comments do not make up for bad code
  • Don’t repeat yourself, only use comments where necessary
  • Avoid commenting out code. It might only be useful in the short term, in the long term it might lead to clutter and rot.
  • Avoid attributions and bylines, version control will take care of that.

7. Use meaningful names

We do naming everywhere in our code. In our functions, variables, classes etc. It is therefore a good idea to choose good and easy to understand names. Here are some tips:

  • Use intention revealing names
  • Avoid disinformation
  • Use pronounceable names
  • Use searchable names
  • Avoid mental mapping. Readers shouldn’t have to mentally translate your names into other names they already know

8. Format your code appropriately

You should choose a set of simple rules that govern the format of your code, and then you should consistently apply those rules. If you are working on a team, then the team should agree to a single set of formatting rules and all members should comply. It helps to have an automated tool that can apply those formatting rules for you. You can actually use EditorConfig a tool that helps developers define and maintain consistent coding styles between different editors and IDEs.

9. Test your code

As much as most programmers hate to do this, this is the only way to prove that your code actually works. With testing you will be able to make big changes to your code without worrying about breaking anything since there will be tests to prove that everything is working fine. Another benefit of testing is if you find a bug, write a unit test for it and fix it, that particular bug is unlikely to ever appear again, and you can prove it with your test.

10. Know your editor well

Choose an editor, know it thoroughly, and use it for all editing tasks. If you use a single editor across all text editing activities, you don’t have to stop and think to accomplish text manipulation: the necessary keystrokes will be a reflex. The editor will be an extension of your hand.

11. Always use source code control

To quote a friend

“Code doesn’t exist unless it’s checked into a version control system”.

Use version control for everything you do. Any version control, SVN, Git, even CVS, master it and use it.

Here are some questions you can answer with source code control

  • Made a change to code, realised it was a mistake and wanted to revert back?
  • Wanted to review the history of some code?
  • Wanted to share your code, or let other people work on your code?
  • Wanted to experiment with a new feature without interfering with working code?

and much more.

12. Don’t leave broken windows, refactor often

As the famous boy scout rule says

Always leave the campground cleaner than you found it

Same rule applies to your code. Whenever you notice any wrongly named variable, duplicated code or wrongly formatted code always remember to change that. No code will ever be perfect, you can only make it better.

13. Don’t program by coincidence

Always know the effect of each line of code you write. If you are using a library or framework before using any function or class, get interested in the code behind it. Most of the code actually have side effects that you may be unaware of. This is how bugs creep in to your system and it will be very hard for you to debug such errors. Taking time to go through documentations can save you a lot of time down the road.

This concludes the list and if you have any more ideas or feedback please share them on the comment section below.

References

The Pragmatic Programmer: From Journeyman to Master

Clean Code: A Handbook of Agile Software Craftsmanship

📝 Read this story later in Journal.

🗞 Wake up every Sunday morning to the week’s most noteworthy Tech stories, opinions, and news waiting in your inbox: Get the noteworthy newsletter >

--

--

Felix Magani
Felix Magani

Written by Felix Magani

Software engineer with a big interest in developing software products that bring positive impact on people’s lives.

Responses (4)