Quick wins for your dev team

Posted: 2018-05-30 17:07:47 by Alasdair Keyes

Direct Link |

---

The joy of contracting is that I often get to work on brand new code-bases with some regularity. The down side is exactly the same.

Over a number of contracts I've noticed a number of things that I've suggested to teams that make their development much easier.

If you work for a fair-sized business or a 'tech' company you can stop reading here, you will look at these suggestions, scoff, and wonder why they need making. However there are a lot of companies that are not 'tech' focused. Their website functionality was bolted onto an existing business that pre-dates the web and the first site was a few scripts written by the most tech-savvy employee they had at the time and grew organically from there. Yes, these code-bases are often a mess and constant tight deadlines for new features and product means it always stays that way and doesn't get improved, but that's reason not to try. It's usually the devs that have to work with the code that get most jaded with the situation, having to work with the code day-in and day-out.

These suggestions are mainly based around PHP, but they can be easily adapted for any other language.

Version Control

This might seem like a no-brainer, but I still see teams without Version control (or still stuck with CVS/SVN). Creating an account through Gitlab is highly recommended, not only do you get their git system, they also have free CI/CD pipelines to allow automated testing which will come in handy if you wish to use these later.

Upside

• Well, you get version control. Multiple devs can work on the same code with less risk of implementing breaking changes.

Downside

• If your team are unfamiliar, a little training may be required to get going. A morning reading up on Gitflow and a few articles on merging will be more than enough to familiarise a team with basic concepts and branching/merging.

Consistent Clean Code Formatting and naming

We've all seen code like this, or if you're unlucky with even less line breaks or line breaks in crazy places

public function fib($n) {if ($n < 0) { return NULL; }
elseif ($n === 0) { return 0; } elseif ($n === 1 || $n === 2) { return 1; }
else { return fibonacci($n-1) + fibonacci($n-2); }}

The code's purpose is not easily understood and the name fib doesn't instantly describe what the function is doing.

PSR-2 is the PHP Framework Interoprability Group's approach which has become the defacto standard for PHP and will make your code much nicer to work with.

Along with nice naming you can turn the above into...

public function fibonacci($n) {
    if ($n < 0) {
        return NULL;
    } elseif ($n === 0) {
        return 0;
    } elseif ($n === 1 || $n === 2) {
        return 1;
    } else {
        return fibonacci($n-1) + fibonacci($n-2);
    }
}

You don't have to strictly adhere to a well-known standard, but using a consistent, clean formatting approach can make your life just a little bit easier.

You can look at doing it in one fell swoop with a tool such as PHP Coding Standards Fixer or do a gradual merge whereby all files that are edited with new code get reformatted before any changes and committed to the repo. Tools such as PHPStorm also have a formatting feature available using CTRL+ALT+L

Upside

• You'll restore some sanity to your devs

Downside

• Reformatting large swathes of your code in one fell swoop will make you nervous. A more cautious approach could be to reformat code before you do new work on a class/file, reformat it, commit it, then do your work.

Adopt a standard documentation format

Each language has it's own documentation format PHPDoc for PHP, Perldoc for Perl etc. What you use isn't so much the key as just using it. A quick one line introduction to a class/function plus documentation on the arguments expected and return values will make your code much more pleasant for people unfamiliar with it.

Again, a rolling adoption is easy and fairly hassle free. Write the required docs for new functions, and then as you edit existing ones, back-fill your documentation. In addition if you use code reviews, get people to check documentation updates as well as the code being committed.

Upside

• Over a short amount of time, you can generate usable documentation for your code base.
• If your IDE supports parsing of documentation like PHPDoc/PHPStorm, then it will speed up your development by showing you function arguments and alerting on exceptions that need to be caught without having to search through your code.

Downside

• There isn't really any, it only adds a few minutes more time spent developing your code.

Basic tests

The chances are if you have not been writing tests from the start, it will not be easy to start introducing tests to old code. The primary reason is probably you won't have written your code in a manner to allow easy testing, you won't be injecting dependencies and your functions will be performing too much work to create concise tests.

Don't let this put you off. Simple tests can be put in place quite easily for even the most attrocious code base.

Firstly, if your team is unfamiliar, take a morning to read up on the different types of tests commonly used (unit, integration, functional, Behaviour etc), the benefits they provide and when you are likely to use them. There are plenty of pages and Youtube videos available via Google to get you started.

Secondly, look through your code base for simple functions that are able to have unit tests created for them. These might be few and far between to start with, but once the tests are written, you can get a little more piece of mind that some future commit is less likely to break functionality without anyone noticing.

If you use a common framework, most of these provide a customised test suite to enable rapid test development for WebApp functionality. A simple, quick and useful test could be to ensure that all access to login restricted URLs returns a suitable message and/or HTTP status code along with a redirect to a login page. This can then perhaps be extended to test valid/invalid login messages and redirects. It's a small step, but you're heading in the right direction.

Testing is a huge subject and you could easily get drawn down a rabbit hole, however, with just a few test, you are already more certain of stopping some errors creeping into your code.

Upside

• Basic functionality can be tested with little overhead to ensure that your code is doing what it should be.

Downside

• Getting more than some basic tests written will likely require a lot of refactoring of your code... which requires tests to ensure you don't break anything, it can get messy if not tackled correctly.

This isn't an exhaustive list, if you find that you are in need of implementing some of these you will likely find that there are lots more changes required in your development processes, but these will allow you to gain a lot of benefit without tying up devs for days or months.

If you found this useful, please feel free to donate via bitcoin to 1NT2ErDzLDBPB8CDLk6j1qUdT6FmxkMmNz