First step with exakat
‘One must review code to live, rather than live to review code’. Reviewing code is part of everyday’s coding life, and it should be kept just what is it : a short trip back to the code that teaches us about what we did. There are three kinds of teaching in code review : learn from one’s own mistakes, eradicate as many bugs as possible, and assess the code. Here is the first step with exakat.
Code review is definitely better done with another developper. Someone else that cast a look on the code and hasn’t build any relationship with it. Anyone who has spend a long time understand that parental feeling that grows until the code is ready for review. Then, it is time to let it go and accept criticism, good and bad. That’s actually hard, isn’t it ?
Human code review is the best, may it be wish an expert or even a junior : it has a higher level of abstraction. So, between a personal code review and an external one, there is room for a code review that doesn’t hurt feelings, and take you an extra mile on the long way to code quality.
The core of the exakat engine
These ideas are at the core of the exakat engine. Exakat is a static analysis tool, designed to review code automatically. It works by reading the code directly, and extracting the various logics and definitions available. Then, it applies an ever growing number of analysis on the code and build a full report.
Starting with the code in a repository, there is mostly two commands to run exakat :
exakat init -p scrummastor -R https://github.com/eleven-labs/ScrumMastor.git exakat project -p scrummastor
The first command initialize the project with the repository. Here, git is used as default, and several other VCS are available, like SVN, Bazaar or Mercurial.
Suggest PHP directive from code
The first report we may check is the php.ini-dist, located in the projects/scrummastor/. This file contains the list of suggested directives to set when preparing the hosting of the application. You’ll find recommendations for :
- mongodb, as scrummastor is indeed based on mongodb ;
- curl, though most of the default values are OK, so a simple link to the docs is available if you want to make sure nothing has been overlooked ;
- realpath_cache_size as scrummastor uses files
- expose_php for security, though this is always legit to check.
The list is actually tailored for the provided code : since mysql or file upload are not used, they are not mentioned here.
With this recommendations file, it is easy to review important directives, and also get a reminder about important directives. This is very useful for the coding team, so they can provide it in a documentation, without writing everything themselves, and for the hosting team.
Suggest PHP compilation from code
Based on the same analysis, exakat provides also compilation directives. Nowadays, PHP is often installed thanks to packages managers like apt-get, yum or brew. Those installation are a time saver. In terms of security and performances, it is safer to compile PHP and avoid any useless extensions : this means PHP has a smaller footprint, and in case of a security vulnerability, it limits the possibilities to exploit the server. So, compiling PHP for an application is always a plus.
;;;;;;;;;;;;;;;;;;;;;;;;
; PHP configure list ;
;;;;;;;;;;;;;;;;;;;;;;;;
./configure
--enable-ast
--disable-ctype
--with-curl=DIR
--disable-dom
--disable-fileinfo
--disable-filter
--disable-hash
--without-iconv
--disable-libxml
--enable-mongodb
--with-openssl-dir[=DIR]
--with-system-ciphers
--disable-pdo
--without-pear
--disable-posix
--disable-session
--without-sqlite3
--disable-tokenizer
--disable-xml
--disable-xmlreader
--with-xmlrpc[=DIR]
--disable-xmlwriter
From the code source, Exakat reports the list of needed extensions, like curl and mongo-db. You may also notice that mongo-db extension has some dependent directives, like –with-openssl-dir, which are reported here for help. And this compilation line disables explicitely any other extension, like pdo, pear or XML.
Analysis of the code source
The previous helps are possible thanks to the internal representation of the code source by Exakat. Exakat spotted the various features and functions, and selected the one that are important for configuration and compilation. Exakat used the same base to apply over 300 analysis. All the finding are accessible in text format, with the following command ;
php exakat report -p scrummastor -T Analyze -format Text
Here is a small excerpt :
/src/ScrumMastor/Provider/ScrumMastorProvider.php:37 Empty Function
/src/ScrumMastor/Provider/ScrumMastorProvider.php:37 Undefined Classes /src/ScrumMastor/Provider/ScrumMastorProvider.php:37 Used Once Variables (In Scope) /src/ScrumMastor/Provider/ScrumMastorProvider.php:37 Should Use Local Class /src/ScrumMastor/Provider/ScrumMastorProvider.php:37 Unused Arguments /src/ScrumMastor/Provider/ScrumMastorProvider.php:37 Could Return Void /src/ScrumMastor/Provider/ScrumMastorProvider.php:14 Undefined Classes /src/ScrumMastor/Provider/ScrumMastorProvider.php:14 Should Use Local Class[…]
274 issues have been spotted in the code, and reported. For each of the issues, you’ll find the source file, the line number and a short description. The one provided in examples are easily understandable : now, if you know the code, you can fire up the PHP IDE and go directly to the line to review it yourself.
Text is a nice format to process long list of issues. Exakat is also able to provide them in various formats, both machine readable and human readable. Below, you’ll find the ‘Ambassador’ report dashboard.
The Ambassador report
The dashboard has an overview of the whole project, tested with PHP 5.6. Exakat supports audits with any version of PHP vrom 5.3 to 7.2. There are breakdown of issues on the left corner, and dynamic graphics by files and by analysis. This allows you to choose which focus you want to have when reviewing code : shall you review as much as possible in the same file, or do you want to emphasize on security only, across the application ?
The ambassador report has a faceted search engine for the issues : select filters by file, analysis or level of importance to narrow your reviews to a precise set of files.
The analysis provided by Exakat are spread in several recipes : Security, performances, compatibility with PHP versions, code quality, dead code. Furthermore, new analysis are added every week, on monday : this is the best day to ‘exakat upgrade’ your version of the engine, and learn more about your own coding.
Each of the analysis is documented with examples. They are usually covering a wide range of subjects and not all may apply to your coding style. That’s perfectly normal : believe me, exakat itself finds issues in its own code, if it were to apply them all at the same time. Ignore the one you don’t like, and focus on the one that are important to you.
Installation
Exakat is available in various flavors : download the phar from exakat.io, try it online with the demo or the Saas services ; get it on docker or Vagrant. The full manual installation is also in the docs online.
Code review as relaxation
The hardest part in reviewing code is to know where to search for problems. Exakat does the hard work of collection a huge library of code smells and error prone code, so you only have to check the actual code and update it according to your coding style.
Indeed, we use it as relaxation. Reading the report is fun : sometimes, just reading about an issue is a good excercice to learn about better coding. Other times, Exakat reports some silly mistakes, and it is always refreshing to fix it, and commit it before anyone else can. How embarassing is it to find a typo in $tihs or $_PSOT (real case) . Quick fixes are a great way to raise the trust level in your code, and fix bugs even before they appear.