コーディング速度を上げる「コメント実装法」

このような迷った経験・苦い経験・悩みはありますか？

・コーディングをしていると、時間が足りない
・他の人よりもコーディングが遅いと感じる
・何かに詰まって調べた後、何をやるべきか分からなくなる
・自分で考えたものを作る時は問題なかったのに、他の人が考えたものを作る時に思ったよりも時間がかかる

今回は私の経験と、そこから考えついた解決策。
実際に試した時の感想をまとめたいと思います。

「コメント実装法」とは…

勝手に名前をつけました。調べても見つからないと思います。

やり方はとても単純です。
実際にソースコードを書く前に、コメントで実装をするのです。

例えばこんな感じです。

// 入力された内容のバリデーションを行う

// データベース用のモデルを作る

// データベースにデータを登録する

// ログインしているユーザーにメールを送信する

まずは、何をやりたいのかをざっくりと整理します。

自分が発案者ではないものを作る時、大概は「要件」や「完了条件」、「設計書」が存在します。それを見れば分かる！という場合でも、騙されたと思ってこの方法をやってみてください。

コツは、この段階では詳細を書きすぎないことです。

アプリケーションアーキテクチャーにもよりますが、役割ごとにソースコードファイルを分割している場合は、この時点で中身が空のものを作ります。

とは言っても、百聞は一見にしかず！

java & クリーンアーキテクチャーを前提で具体的に見ていきましょう。

public class XxxController {
    private final XxxService xxxService;

    public void hoge() {
      // 入力された内容のバリデーションを行う
      xxxService.fuga();
    }
}

public class XxxService {
    public void fuga() {
         // データベース用のモデルを作る
         // データベースにデータを登録する
        // ログインしているユーザーにメールを送信する
    }
}

※メソッド名やモデル名は仮ですが許してください。

手間ではないですか…？

人によってはその通りかもしれません。

…実は、この方法を今使っていません。理由は単純。この方法を繰り返し行うことでトレーニングができ、頭の中で整理する力がついたからです。

自分なりの方法が見つかって、結果的に早くなれば良いのです。

私が陥っていた問題点は「やりたいことを見失って、対応迷子になっていた」ことです。

人間、複数のことを同時にこなす事はあまり得意ではありません。出来る事なら、新しく挑戦すること・慣れない作業をする時は、一つの事に集中できる方が望ましいです。

また、複数の箇所にやるべき作業が点在するよりも一箇所にまとまっていた方が、ほんの少しですが視点の移動がなくて済みます。それに、コメントであれば自分が分かりやすい言葉で、今時点での整理した内容で書けるのもメリットの一つですね。

この後のコメントを書いていく粒度、それは人によって違う形で良いと思います。効率的にコーディングを進める為の方法ですので、コメントを書き過ぎて遅くなったら意味がありません。
ですが、迷いそう…という心配な気持ちがあれば、細かく書くのも一つの手かと思います。結果的に、早く終わることが大事なのです！

具体的例として挙げたのは、新しい実装のパターンでしたが、既存の実装を改修する・修正をするパターンも当然遭遇します。

その場合は、対応箇所に「どうしたいのか」を書けば良いのです。何か懸念点があれば、その該当箇所にコメントをすれば良いのです。どこで何をやるべきなのかコードを読む力は必要ですが、何度も他の人のコードを読んでみることで力をつけましょう。（何を見れば良いか分からない方は、「調べたい言語(ex. javascript, java, php)」と「GitHub」の二つで調べると沢山見つかるかと思います）

もう一つだけ、この進め方のメリットをお伝えしておきます。それは、手戻り（レビューに伴う修正）が少なく済む可能性があるということです。

レビューは全ての作業が終わった後だけじゃなくても良い

ということですね。つまり、最初にコメント実装法を実践した時に一度レビューをお願いする方法です。

…結果的に早くなったのか？気になりますよね。

レビュー戻りが少なくて早くなった時もあるし、レビューの時間が増えて本来の作業ができなくなった時もありました。

では、何故上手くいった時とそうではない時があったのか。早くなった要因はシンプルです。

レビューが出来る人数がそこそこいた

その点に尽きます。上手くいかなかったのは、この逆ですね。
…実は、このタイミングでのレビューはとても難しいのです。

先程も書きましたが、どこまでの粒度をコメントとして書くのかが人によって違います。その差によって、まだ動くものを作れていないのに、やり取りの時間がかかる可能性があります。方向性がこの時点で間違っていたら、意味がないのは分かりますよね・・。

そういう時はルールを決めましょう。
一例にはなりますが、

・聞いておきたい内容があれば、想定を聞くコメントとする → 通話の併用も有効
・全く想定と違う場合は、モブワークでコメント実装をサポートする
・言葉の表現は、認識のズレがないようであれば目をつぶる

結局メリットは？

整理がしやすくなるという点以外にも、副産物のようなメリットがありました。

・実装が慣れていない人の進捗が分かりやすくなった
・実装している人の頭の中が分かった
・整理に時間がかかりやすい場合は結果的に早くなった
・出来る人の頭の中を知れて共有ができた

短期間にスキルアップをするために、モブワークはとても有効です。ですが、その時間を確保できる場面は中々ありません。
けれど、スキルアップも促進していきたい。

そんな無茶な場面に遭遇した場合は、試しに導入してみてください。ちなみに、このコメント実装法は、短期間にしましょう。慣れてくれば、自然とできるようになっています。やめるタイミングは、そのチーム・人によって違うと思いますので、見極めましょう。

まとめます

実践方法

・コーディングをする前に、コメントで何をするかを書く
・アーキテクチャーに沿った形で何をどこに実装するかを整理する

注意点

・コメントを書くことが目的と思わないこと
　・整理をするための方法として活用する
・細かくコメントを書きすぎない、書いてもらおうとしない
・モブワークや通話でのコミュニケーションを積極的に取り入れること
・整理したコメントはコーディングをしたら消す
　・価値がある、チームの方針に沿っているコメントは残す
・ずっと取り組むのではなく、短期間だけに限定する

メリット

・何をすれば良いのかを自分の中で整理することができる
・レビュー戻りが少なく済む
　・全部修正をする前に軌道修正ができる
・頭の中を知ることができる
　・どこで詰まっているのかが分かりやすい
　・引継ぎがしやすい
　・技術共有ができる
・モブワークをするよりも少ない時間で同じような効果が得られる

この記事を読んだ人の、少しでも力になれば幸いです。