Documentation Driven Development (DDD) — I thought, I discovered “Something New!”

“ Any fool can write code that a computer can understand. Good programmers write code that humans can understand. ” — Martin Fowler -

Documentation Driven Development (DDD) — I thought, I discovered “Something New!”

> “ Any fool can write code that a computer can understand. Good programmers write code that humans can understand. ” — Martin Fowler

Yes, your must never write code for yourself and that is what I was doing while working on infrastructure and APIs development. For clients and other developers, we started writing the API /Infrastructure documentations (apart from requirement and specification document). This document provides a crystal understanding of features coming in iterative releases and APIs to our clients. It also strengthens our practice of — feature can not be marked as delivered if documentation and test cases are not written.

Let me reiterate, this documentation is not explaining the test cases, but explaining what these functional calls are, what the required inputs for the calls are, what the required outcomes are, what the error messages/codes are, what the client actions are and what the error strategies should be adapted in case of errors.

To have a clear understanding of such documentation, Let’s bring back our Pizza application that we need to implement (as we need food to talk). This application provides details description of functional and API calls required to order, track and retrieve details of a pizza. I will talk about a section of this documentation —

Get a Pizza — This call will return the information about a pizza with pizza\_id or if pizza\_id is not passed, it will filter out the response on the basis of request parameters.

Resource URL — \[GET\] /pizza/{pizza\_id}

Resource Attributes — What are the resource attributes ? e.g. pizza\_id, pizza\_delivered\_by, pizza\_prepared\_by etc- These are the attributes that define a pizza.

Relational Resources — There will be relational resources for pizza or maybe pizza is related to other resources, for e.g.

\[GET\]-

/pizza/{pizza\_id}/toppings/

/pizza/{pizza\_id}/toppings/{topping\_id}

/delivery/{delivery\_id}/pizza

/deliver/{delivery\_id}/pizza/{pizza\_id}

Authorization Header — Information that requires in making sure that I am authorized for to get the pizza details (i.e. access\_token, basic\_auth- user:password etc-)

Authorization Error Message — If I don’t get the pizza details.

Request Parameters — Request parameters that can help to filter our the pizza details e.g. pizza\_id, delivery\_id, pizza\_delivered\_by, delivered\_before, delivered\_after etc-

Error Message — If GET request is not proper e.g. missing parameters

Internal Error Message — If GET request is proper, but your server can not accommodate the request for whatsoever the reason.

Response — How your pizza response will look like, e.g. JSON representation of your pizza details along with standard API response.

Response Parameters — Response parameters if there is any information that you need to pass related with this additional resource

Cache-Control header — If you API supports cache control header. (If you API is not doing, you should start doing it.)

Other documentation details…

Look, with the above details, we have covered all the trivia that our clients or other developers would require to use the “Get A Pizza” call and now you deliver the code to implement the requirement.

You will start — - Write your test cases (if you are following [Test Driven Development, TDD](http://en.wikipedia.org/wiki/Test-driven_development)) to test your calls described in the documentation. - Write your code to implement the functionalities as described in the documentation. - Handle the errors, cross check with the documentation, you return the same error\_code and error\_messages that your client would expect. - Your response\_code and response\_message are the same formats as described in the documentation. - Refactor both code and documentations along with the changes.

With my experience, the documentation is a metadata about your features, It describes your thought process and insights before writing a code and with the documentation before actual code, you get early peer reviews, feedback and you speculate “how it is going to be used”.

This documentation provides leeway to your clients and other teams so that other teams can prioritize their work by the time, they receive the actual implementation.

I would recommend it as great practice in API development (infrastructure development too) where your documentation can captivate your clients for the success.

We love coding, let’s have other people love your code with DDD. Happy coding!

I welcome your comments and your experience if you are following the documentation driven development.

Originally published at [www.linkedin.com](https://www.linkedin.com/pulse/documentation-driven-development-ddd-i-thought-discovered-nigam).