下書きしてからコードを書く

はじめに

エンジニアになって今年で5年？6年目？になるのですが、
1年目から「コメントで下書きをしてからコードを書く」
というやり方で今もなおコードを書き続けているのですが、
結構良い書き方な気がしているので、
今回はそのやり方についてアウトプットしようと思います。

サンプル要件

やり方を説明するにあたり、下記に書いた要件を満たすコードを書く場合を想定して
話を進めていきます。

• 商品詳細・配送状況を閲覧できる画面であること
• 配送状況は下記によってメッセージを変えること
  • 注文日≠null かつ 配送日=null：「配送手続きをしてください。」
  • 注文日≠null かつ 配送日≠null かつ 配送完了日=null：「配送中です。」
  • 注文日≠null かつ 配送日≠null かつ 配送完了日≠null：「お客さまに商品が届きました。」

STEP1: とりあえずControllerにやりたいことの大枠を書く

class SampleController extends Controller
{
    public function sample() {
        // 商品の情報を取得

        // 配送状況を判定
    }
}

今回だと大枠こんな感じですかね。

STEP2: より具体的にやりたいことを書き込む

class SampleController extends Controller
{
    public function sample() {
        // 商品の情報を取得
        // 商品テーブル.id = 表示したい商品のIDを取得

        // 配送状況のメッセージを取得
        // 注文日≠null かつ 配送日=nullの時は、「配送手続きをしてください。」のメッセージを付与
        // 注文日≠null かつ 配送日≠nullの時は、配送完了日=null：「配送中です。」
        // 注文日≠null かつ 配送日≠nullの時は、配送完了日≠null：「お客さまに商品が届きました。」
    }
}

こんな感じ。
やりたいことの塊ごとに改行して、ブロックをわかりやすくすると、
よりいいかなと思ってます。

STEP3: Controllerから処理を書きたい場所を呼び出して呼び出し先にコメントをうつす

今回だと
「商品の情報を取得」
「配送状況のメッセージを取得」
の塊をそれぞれServiceに移行していきます。

Controller

class SampleController extends Controller
{
    public function sample() {
        $sampleService = new SampleService();
        // 商品の情報を取得
        $sampleService->fetchSample();

        // 配送状況のメッセージを取得
        $sampleService->addStatusMessage();
    }
}

Service

class SampleService
{
    /**
     * 商品の情報を取得
     */
    public function fetchSample()
    {
        // 商品テーブル.id = 表示したい商品のIDを取得
    }


    /**
     * 配送状況のメッセージを取得
     */
    public function addStatusMessage()
    {
        // 注文日≠null かつ 配送日=nullの時は、「配送手続きをしてください。」のメッセージを付与
        // 注文日≠null かつ 配送日≠nullの時は、配送完了日=null：「配送中です。」
        // 注文日≠null かつ 配送日≠nullの時は、配送完了日≠null：「お客さまに商品が届きました。」
    }
}

こんな感じ！

STEP4: コード書く！

で、コメントをもとにコードを書いていくという感じです！

コメントでブロックが分けられているので処理が散らばることもないし、
「あ、これ実装してないや」
みたいなことも少なくなるかなと思ってます。

今のところ、あんまりデメリットはないのですが、一応かくと
コメントが大量になるので、開発が終わったらコメントの取捨選択をしていく必要がある感じですかね。

まとめ

全ての実装をこの方法でやってるわけではないのですが、
処理が複雑になるものほどこの方法で開発してます。
頭も整理できるし、設計の練習にもなるのでおすすめです。

以上！