Saturday, 2 March 2013

Code quality


I've been involved in many discussion lately about code quality. Unfortunately not so much was satisfying. I had the impression that high quality code is still a mysterious thing that only best developers know.
Nah, it's not true at all. Code quality is for me 30% talent and 70% simple environmental / behavioral setup. To bring all the mystery to light I'd like to share how I'm dealing with code quality assurance. It's really not rocket science, trust me. Most things I'll explain needs a one-time investment, you setup once and live with it most of the times. So no excuse not to do it now, if it's not in operation already.

But first, why? Simply because this topic has surprisingly little attention. We are coders. We don't take our clothes down in public, we don't cook, we don't brew or anything like that. We produce code and that's what we're judged by.
It's a self boosting learning curve. Whenever you make your code a bit better you see the next stage you can evolve to. And during quality assurance you meet with the best industrial practices. Lazy coding usually comes with the lack of active code reviews.
Apart from that two the project also has many benefits of a good code. Saving cost on a long term. Less risk, easier maintenance, etc.
Also for me a huge point is transparency. Having developer experience in the last couple of years showed me that proper code has a limited way of describing information flow - depending on your language and project. In Drupal you expect to see hooks, in PHP you expect to see array operations, in JavaScript you expect having prototype extensions and function tricks ... any change and unnecessary variation from these patterns will make code readability harder and longer in time.
And finally - just heard a great analogy today - your code should look like a Saturday night, not like a Monday morning.

So the list ...

Everything starts with an environment. Your environment is a single most-important parameter of the whole quality assurance process. Use any kind of systems - but make sure you can use every single tool you have to. If you cannot install a tool - use a different OS. Or AMP stack. I've literally tried more than 50 different operation systems. From various Windows, BSD, Unix, Linux to OS-X. Make sure your error reporting level is on maximum:

error_reporting = E_ALL | E_NOTICE
display_errors = On
display_startup_errors = On

Usually I keep multiple settings file (php.ini, my.sock, httpd.conf, ...) in order to change my environment quickly. So whenever I would like to test my project in a certain condition I just redirect the setting. I can even change PHP versions in no time with this.

Use the most visual terminal shell. I use zsh just because of the amazing ecosystem is has and the massive plugins.

Install all the debugging tools: XDebug and XHProf just couple of the most important ones. Set them up in a way that anytime you can get a report if you need, and don't slow down your server otherwise. I tend to comment them out when I don't need it, but a small script could do that as well. For the result analytics it's the best if you have a local virtual machine with KCacheGrind installed in it.

Then the next section is the quality assurance tools. There are so many and you can even find Drupal specific configuration files for most of them. PHPUnit is used for making unit and functional (with the Selenium additions) tests. PHPLoc, PHPDepend, PHPCopyPasteDetector, PHPMessDetector, PHPCodeSniffer and PHPCodeBrowser are just a few of those. It's really easy to intall them through the PEAR repository and it's ready to use. These tools can look at your code and see how consistent, is there any structural problem, smelly code, inefficient structure or duplications.

If you're in Drupal you have more special tools already. Make sure you're using logging on a maximum level. You can get SQL reports in Views or with Devel module. In XDebug you can set array dumps and error log messaged to contain more level nesting and arguments and many other details. And let's not forget about the Coder module which can check some Drupal standards for you. Also - read all the Drupal coding standards handbook pages: http://drupal.org/coding-standards

Next thing is crucial also: use a proper code editor. Emacs, Vim or Notepad++ is a text editor, not a professional coding environment. So far I've found PHPStorm far the best. Its visual feedback tells me each time I don't follow the coding conventions, or left an uninitialized variable, or something is not used os simply doesn't make sense from the execution point of view. The code verification that comes out of the box with PHPStorm would solve days of tedious code cleaning and fixing.

Make sure you know the PSR standards. It's getting more and more of a mandatory requirement for large projects.

Then the fourth element is code reviews. As a general rule no code can get to the master (or alike) branches without code review. Having and doing code reviews is an amazing occasion to learn coding. Practically it should be a controlled process, something similar to what BitBucket is doing. There you can merge-requests where participants can check your code and help if it needs by explaining what part has to be changed and why. There are small things that can make the whole review process really good. You should always explain why you disagree with a code snippet. And usually you only should disagree if there is a logical reason, and it's not just because your style is different.
To make reviews efficient and easy take a small part, verify that and report what you did exactly. That's much easier to pick up by reviewers and at the making sure all critical point was covered.
If you do code review it's better to make it 2 at least. First check the syntax and conventions and then the semantics and the large picture.

Of course it's not the end, there is a lot more. Also let me add that many of these tools can be used with Jenkins, so you can perform these checks whenever you want. Or you can attach them to your git commit hook. So it's gonna be an even more automated process. And these are just really tools. Nothing theoretical code architecture level magic.

---

Let me know if you use similar tools to assure code quality. I'm always interested to learn new things.

Peter

No comments:

Post a Comment