poteto

Documentation-Driven Development

The philosophy behind Documentation-Driven Development is a simple: from the perspective of a user, if a feature is not documented, then it doesn't exist, and if a feature is documented incorrectly, then it's broken.

• Document the feature first. Figure out how you're going to describe the feature to users; if it's not documented, it doesn't exist. Documentation is the best way to define a feature in a user's eyes.
• Whenever possible, documentation should be reviewed by users (community or Spark Elite) before any development begins.
• Once documentation has been written, development should commence, and test-driven development is preferred.
• Unit tests should be written that test the features as described by the documentation. If the functionality ever comes out of alignment with the documentation, tests should fail.
• When a feature is being modified, it should be modified documentation-first.
• When documentation is modified, so should be the tests.

poteto

import Ember from 'ember';

export default Ember.Controller.extend({
  appName: 'Ember Twiddle'
});

poteto

import Ember from 'ember';

export default Ember.Controller.extend({
  appName: 'Ember Twiddle'
});

poteto

import Ember from 'ember';

export default Ember.Component.extend({
});

poteto

import Ember from 'ember';

const { Controller } = Ember;

export default Controller.extend({
  result: 0,
  actions: {
    add(x, y, z) {
      return this.set('result', parseInt(x) + parseInt(y) + parseInt(z));
    }

poteto

import Ember from 'ember';

export default Ember.Controller.extend({
  appName: 'Ember Twiddle'
});

poteto

defmodule Json do
  def flatten(%{} = json) do
    json
    |> Map.to_list()
    |> to_flat_map(%{})
  end
  def flatten(%{} = json) when json == %{}, do: %{}

  defp to_flat_map([{_k, %{} = v} | t], acc), do: to_flat_map(Map.to_list(v), to_flat_map(t, acc))
  defp to_flat_map([{k, v} | t], acc), do: to_flat_map(t, Map.put_new(acc, k, v))

poteto

# Example taken from https://github.com/edgurgel/httpoison
defmodule GitHub do
  use HTTPoison.Base

  @expected_fields ~w(
    login id avatar_url gravatar_id url html_url followers_url
    following_url gists_url starred_url subscriptions_url
    organizations_url repos_url events_url received_events_url type
    site_admin name company blog location email hireable bio
    public_repos public_gists followers following created_at updated_at

poteto

defmodule MyApp.Terraformers.LegacyApi do
  alias MyApp.Clients.LegacyApi
  use Plug.Router

  plug :match
  plug :dispatch
  
  get _ do
    %{method: "GET", request_path: request_path, params: params, req_headers: req_headers} = conn
    res = LegacyApi.get!(request_path, req_headers, [params: Map.to_list(params)])

poteto

# terraformers/foo.ex
defmodule MyApp.Terraformers.Foo do
  use Plug.Router

  plug :match
  plug :dispatch
  
  get "/v1/hello-world", do: send_resp(conn, 200, "Hello world")
  get _, do: send_resp(conn, 200, "Handle all GETs")