Writing Code you can Read

When you decide to get into the software development space you anticipate that the majority of your day will be spent sitting at your desk and coding all day. Sadly, this is not a reality because the truth is alongside much your time being taken up in conversations, meetings, documentation and admin – you will probably spend a lot more time READING code than actually writing it.

Which is why if you really want to grow as a developer – you don’t just need to become good at reading – but actually writing code in a way that makes the lives of your fellow coders a lot easier, so that they – like you – can end up doing less reading and more coding every time they need to review, modify or update the work you have produced. Of course, you could always be a bit of a masochist and get joy out of writing hard to decipher code for your colleagues – though chances are that joy will be short-lived when they throw it back at you when reviewing your merge requests.

So today I want to start your new coding year off with some tips on writing code that makes it a lot easier for those around you to read it and understand exactly what is going on. This is nothing ground-breaking and you can find similar tips available on many different platforms. That doesn’t make this any less important though as I still see many people struggle with the concept of writing code that is easily readable. There are many things to look at, but with the purpose of keeping this article as readable as your code should be – I will refrain from going into too much pedantic detail and just provide the basics to help you along the way

As you will discover, writing readable code is actually a lot more time consuming and difficult than just writing code to get the job done – but the benefits and reduction in future maintenance most certainly make it worthwhile.

1)     Space your code out

As a coder if often makes sense to keep everything in as few lines as possible – but this doesn’t make it easy for another to follow what you are doing. Rather, make things easy to read by making use of clear indentation, line breaks, space and keeping to the general rule of having each line of code only declare or do one thing.

Bad

const userData=[{userId: 1, userName: 'Jan De Beer', memberSince: '08-01-2017', fluentIn: [ 'English', 'IsiXhosa', 'Portuguese']},{userId: 2, userName: 'Thembi Dlamini', memberSince: '02-11-2016', fluentIn: [ 'English', 'IsiZulu', 'German']},{userId: 3, userName: 'Alwyn Smith', memberSince: '29-08-2013', fluentIn: [ 'Afrikaans', 'English', 'German']},{userId: 4, userName: 'Hirohiro Matumoto', memberSince: '08-05-2015', fluentIn: [ 'Mandarin', 'English', 'German', 'Japanese']}];

Better

const userData = [

 {

   userId: 1,

   userName: 'Jan De Beer',

   memberSince: '08-01-2017',

   fluentIn: [

     'English',

     'IsiXhosa',

     'Portuguese'

   ]

 }, {

   userId: 2,

   userName: 'Thembi Dlamini',

   memberSince: '02-11-2016',

   fluentIn: [

     'English',

     'IsiZulu',

     'German'

   ]

 }, {

   etc...

2)     Make your names as self-explanatory as possible

It goes without saying that variable and method names should not only fit into a necessary standard across the team, but it should be easy to derive its purpose and intention just from reading it. You can invest a lot of time in writing comments to explain what your code does or simply just write longer, but more detailed names that can do this for you.

Making names easier to pronounce and allowing for easy distinctions between purpose and form will go a long way in helping to understand what is going on with your code.

Bad:

protected $d; // elapsed time in days

Good:

protected $elapsedTimeInDays;

protected $daysSinceCreation;

protected $daysSinceModification;

protected $fileAgeInDays;

3)     Keep your functions short and simple

The smaller the function, the better. Having a long complex function makes it difficult to maintenance in future and so you want to keep it as short as possible and ensure that it only does one thing. Having a function with multiple purposes is going to be a nightmare to debug and maintain.

It is also helpful to throw exceptions rather than return different code dependent errors. Exceptions will provide the right amount of detail with what is going on so that the context of it is clear and it can make the debugging aspect of your code a lot easier. This takes a lot of practice and work to get right – but unless you like dissecting code for hours on end – you’ll want to get this right.

4)     Smart comments

As mentioned you don’t need to comment your code if it’s written in a self-explanatory fashion – though that doesn’t mean comments aren’t useful. Especially if the feature you are working on remains complex or if there are consequences within the code (like long execution time) then it makes sense to include these into the comments. Additionally, another bad thing to do is comment out code that is not working. While this makes sense while you’re debugging or working on a new feature – it’s not something you should be including into your code merge. You may have the intention of “doing this later” – but then why include it at all?

5)     Consistency

None of the above steps would be beneficial if you changed the way your code looked every time. If possible, agree on a standard for how code should look as a team and then stick to it. This will make the task of reviewing and reading code quicker for everyone and make the work place a happier one for everyone.

6)     Testable

A good indication of well written code is that it is easy to write unit tests for it and has a high coverage of unit tests included. If you’re struggling to write tests for the code you’ve written nor able to get a high code coverage in your unit tests – chance are that what you have written is more complex than it needs to be and you may want to consider some refactoring here. This might not be the favoured aspect of many developers code – but writing good unit tests is just as important as writing good code and goes a long way in helping a user understand what your code is supposed to do by seeing what tests it needs to pass in order to work correctly.

Unit tests on their own are another big topic which I will be going further into in a future article, but much like production code – unit test code should be easy to read, keep things simple and be quick to execute.

Articles on readable or clean code are not the most exciting to read, but nonetheless remain relevant regardless of how experienced you are as a developer. These may seem like basic things to do, but if we don’t regularly review our own code, it’s easy to miss out on these things and end up with code that is going to cause some long-term headaches.