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.
- Start with writing a description of your component, why you are creating it, and what is the aim you would like to accomplish here, what does it do etc.
- If there are modifications being done, then those should be logged by creating a Changelog.md file attached to your component. Maintain a specific format to have consistency throughout.
This is something we follow, hope this is pretty clear:
CHANGELOG.md file sample:
- It’s good practice to add @see, referencing the class, which will help easily navigate to that class definition by using IDE like PHPStorm, or editors like Sublime etc with just one click.
- Add @TODOS wherever necessary. It’s very important if you feel your code can be improved in future and you have the ideas on how to do it, but not enough time at the moment. Mention what needs to be improved above that code snippet. One good example could be:
- Create README.md files so that others can easily understand what is the working of the module. For example:
- A “Docblock” is a special code comment that offers an explanation of the purpose, arguments, return values, and throw exceptions for a block of code.
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
- Of course naming conventions depend on the language you are using ( examples: Zend, Google style guides for PHP, CSS, Javascript, Java, etc ) but the main idea is to use descriptive and meaningful words. So, you should avoid calling your variables: xx, yy2, test1, test2 and so on.
- For example, lower_case for PHP variables and functions, camelCase for JS variables and functions, lower-case-hyphenated for CSS ID's and classes, UPPER_CASE for constants.
- We should name our variables in a way which easily explains the type of data they contain. Similarly in case of functions, they should describe what kind of functionality they are providing. This is called self-documenting code. Functions should tell what they do, not how. This is called abstraction which allows the underlying implementation to be changed without changing the function name.
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:
- Avoid using hardcoded values like absolute file paths, URLs etc unless it’s a matter of life and death (:P)
- Avoid using magic numbers in your code. Basically it’s a hard-coded value that may change at a later stage, and hence become hard to update. Almost all numbers other than 0, 1 or 2 should be assigned to a constant at the top of the file. This provides a single point of change if the value changes, rather than a search-and-replace that could affect many files and potentially introduce bugs.
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:
-
PHP:
- We use PHP Code Sniffer with Drupal integration. One can easily configure it with your editors such as Sublime which will show common PHP errors on save, which saves a lot of time and prevents errors before committing your changes.
-
Javascript:
- We have Drupal JavaScript coding standards (note - these vary in several ways from Mavericks standards) in place but we use JSHint for listing our JS related code checks.
- Wherever Drupal's JS formatting conventions conflict with JSHint, JSHint supersedes.
-
SCSS:
- We do not have any SCSS related documentation on Drupal.org but we do have Drupal CSS coding standards (these can be applied to SCSS code).
- You can find some documentation related to SCSSLint here.
- Also it’s good to checkout Compass best practices as well.
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.
- First step is to register Travis-CI, which you can also do with your github account.
- Setup the .travis.yml file, This file handles the build of your environment and also the execution of the phpunit files.
You can check the simplest basic configuration here:
When you have the phpunit test in place and if it is passed, it will show something like this on your commit:
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.
Visit the original post here. Thanks for reading :)
Top comments (6)
Function and comment documentation are key things to ensure speed of coding (including yourself when reusing one of your own "old" functions/classes/algorithms).
I use this rule for function signatures: "What" is more important than "why". "How" may be useful in some instances.
For in-code comments I use the rule: "Why" is more important than "what", and "how" is usually immaterial (depending upon the language).
I find this results in short, to the point comments/documentation that allows me to quickly read/re-read a block of text and immediately know how to use it or why it may now be broken. Having to re-read code is immensely non-productive and can really derail your "flow" when creating code. Contrary to those people that either have no lives or have massive amounts of time to read someone else's code base to be able to use it. One well thought out sentence can save 15 minutes of digging, multiply that by 50 times in a week/month and you can gain entire days back.
An inexperienced developer may comment "Increment i", but what they really meant to say was "Normally we can't increment i but because of blah reason, X breaks". The incrment may have been non-obvious while it is crucial to the functioning of the entire system... it may have also been just a loop increment. Smart comments can multiply (10x) the speed of understanding of a code block.
Absolutely! Thanks for the detailed explanation.
I have been following the similar rules, for instance, people usually tend to write what the function is and not describing what the function does. So I see your point here.
Commenting with useful stuff saves a ton of our time.
Great.
I would argue though with the usage of TODOS. Never let them spawn like mushrooms as they tend to promote procrastination among others reading/contributing to the code.
Of course, I agree, too much of anything results in a negative outcome. And clearly, if you have a lot of TODOS in your project then its likely that it will result in a lot of technical debt.
I have the belief that any coding standard not enforced by a linter is optional - because if it isn't the code will soon look like it is.
hmm Makes sense.