Coding for others – Part 1

This is part one of a two part mini-series. The second part goes into more detail on tips for improving your code’s readability and maintainability.

The vast majority of developers will, at some point in their career, use code written by a third party. This might be code written by a co-worker, a little snippet from a repository such as Snipplr, or a comprehensive language framework such as CodeIgniter or jQuery.

Now if you have actually ever had to go beyond just using any code written by others, and instead had to delve into the guts of the code itself, you will probably have seen a mix of code quality. Poorly written code can be a nightmare to understand. Well written code, on the other hand, can make it feel like you are reading prose; you can instantly get a feel for what is happening. Typically, well established code libraries will tend to have clear, easily readable code, whereas your co-worker might be turning out code that looks like it is written in Klingon.

So what does your code look like? How easy would it be for other people to pick up your code and figure out what it is doing?

Even if you are working on your own, writing code intended just for yourself, it is important to have a strict coding standard that you work to. You never know in the future who will have to look at your code and figure it out. And even if that person in the future is you, it is amazing how quickly you forget what a particular function or class does. The extra time taken to carefully craft and comment your code so it is easy to pick up again after a break will be paid back a hundredfold when you don’t have to hunt through file after file tying to figure out what your mind was thinking when you wrote it.

If you are writing code explicitly intended for others to use, then the case for clear, expressive code is even more pressing. It is your obligation to ensure that the code is as readable and easy to understand as possible; doing so will benefit you as well as your users, helping to cut down on requests for help or clarification. Good code speaks for itself and needs little documentation.

So how do you make your code easy for others to follow? In the Part 2 of this series I will go into detail on how you can make your code expressive, easy to read and simple for another developer to pick up and understand.