A year back, I was working on a project that taught me how to keep my code clean, modular, reusable, and all those terms that seem fancy, but are actually good for you in the long run. Interesting? Yeah a bit.

But what did I do after getting into those practices?

I made mistakes. Believe me, a lot of them. But with every mistake, I learnt a lot of stuff that I had never considered before. It helped me in my thinking process, on how we should build things, what steps we need to consider when we are developing/extending a feature. And most importantly, these learnings were not just personally helpful, but also crucial for team growth.

At first we used to get frustrated because we had to follow the additional process like adding documentation, maintaining changelog files, following the code standards, and keeping them consistent throughout the team. These extra steps seemed cumbersome and we were not able to relate how this can be useful for us (team). And we are still learning/improving everyday in this respect. But after few months we started loving and improvising the process.

So here I am, sharing my what I have learnt. And trust me when I say, after getting this into practice you can’t live without following this.

This post is focused on what practices we follow everyday to make our lives easier (More focused on PHP/Drupal but can be followed, we follow pretty generic practices).

Let’s start off with simple things:

Commenting and Documentation Standards

Commenting doesn’t mean adding a bunch of comments and random documentation anywhere while coding. There are things which you should mention to make your colleagues’ lives easier, and yours as well.

This is something we follow at Srijan, hope this is pretty clear: CHANGELOG.md file sample:

Changelog sample

Function referencing

Todo example

Readme example

Docblock example

Something very informative in a simple tweet I found:

Formatting

This might include indenting, whitespace, brace positions, and new lines and this can be different according to different languages. In our case, this is specific to PHP (Drupal). There are a lot of plugins available in editors to beautify your code.

Naming Conventions

Portability

Keep your code as loosely coupled as possible. It is “portable” in that the amount of work required to move it from one platform to another is low. There are few things we should have in mind while coding:

Linters

There are different types of tools available to find syntactic discrepancies in general, especially in interpreted languages like JavaScript, PHP, Python etc. They can also be used as simple debuggers for finding common errors. Here’s a look at the common linters we use at Srijan:

Reusability

This is something we are working on quite extensively. We are building reusable components which can be used in across different websites (which have almost the same purpose). These components will provide the basic functionality and styles which can be overridden in different websites according to their own requirements. The most important thing here is to identify what functionality can be turned into a component.The degree to which your code is reusable is largely based on how tightly it’s coupled with the rest of your code base. A good example can be building a banner slider which can be used in most of the websites.

Modular

This basically means keeping your code independent of others, so that one bad change to your code does not break everything else. This is similar to the concept of coupling in object oriented programming. It’s like breaking the website into its basic independent parts of a more manageable size.

Use Continuous Integration Tools

We use Travis CI. It’s a distributed continuous integration service used to build and test projects on github. The service is free for open source projects. You might be wondering why you didn’t you use it before! 😛 Don’t worry, It’s never too late and pretty easy to setup with your github repositories.

You can check the simplest basic configuration here:

travis repo example

When you have the phpunit test in place and if it is passed, it will show something like this on your commit:

travis success message

You can check the simple Travis setup here:

This .travis.yml should be at the root of the project. Travis only runs builds on the commits you push after you’ve enabled the repository in Travis CI.

Code Reviews We have pretty awesome code review process in place. But this blog is already too long, so I shall cover that in my next blog. Stay tuned.