Luke Curtis

Luke Curtis

Software Developer and Project Manager

Contact Me

Documentation Driven Development (DDD) - Part 1

12/03/2019 (5 months ago) | Luke Curtis

Testing is super important. I can't stress enough how critical it is to an applications viability as not only a platform but also as a scalable solution.

Without testing you open yourself up to so much maintenance and extra work you could easily avoid. Lots of people use Test Driven Development (TDD) or Behaviour Driven Development (BDD) and for that I would 100% recommend getting this course for using TDD in production.

However a lot of the time, when working in an agency more-so, you find that clients will simply not have the budget to allow for testing, and since it's always hidden behind the scenes, they usually can't see the benefits of where their money is going.

When in this scenario, I always try and stick to what's called Documentation Driven Development (DDD). By doing this you get to scale your application along with your clients requirements, and then later write your unit tests to accompany the documentation you write along the way.

This is the first part of a series that I hope to write out in the coming weeks.

In Laravel world, the first step couldn't be easier. Using mpociot's amazing Laravel API Documentation Generator we're able to tightly couple our documentation to our endpoints with a beautiful interface and easy to maintain code. Lets dive into an example.

A user update method

A user update method

What's going on here is pretty simple, we're updating a user model in our API, but once this is all done and dusted, what about when we need to refer back? Well thats where our documentation can come in handy. By adding in a code block like the following:

Notice all we're doing is adding a docblock here? Now when we run up php artisan apidoc:generate it will compile this docblock down into a beautiful reference for us (and other users of our API) to use
It's even used on Laravel Forge!

It's even used on Laravel Forge!

It really couldn't be simpler and it's the first step to making a more manageable and scalable application. If you have multiple people on one project it's a no brainer.

P.S. I'm not saying this is by any means the "correct" or "preferred" method of developing. On the contrary I feel this, in combination with TDD is probably the most viable solution. But doing this is easily the best bang for buck when it comes to having consistent and manageable projects.