Webエンジニアの皆さん、ドキュメントちゃんと残してる？コーディング効率化のためのドキュメント作成テクニック3選

Webエンジニアの皆さん。Webサイトを作っていると、同じような問題に何度も直面することがありませんか？

「前にもこういうことがあったな……でも、どうしたんだっけ？」と思いつつ、毎回その場で解決策を考えコーディングする。そんな経験は誰しもあるでしょう。

今回はこのような問題に対して、すばやく合理的に対応するための「Webプロジェクトのドキュメント作成テクニック」を3つご紹介します。

1. コードにコメントを残しておく

コードに適切なコメントを書いておくことは、コーディングの基本であり、かつ重要なポイントです。

「新しいファンクションの上に、目的やプロジェクトとの関連性について数行の説明を入れる」方法がもっとも一般的です。こうした工夫をしておくことで、エンジニアやデザイナーを含む関係者すべてがファンクションを理解しやすくなります。

作業の混乱原因は、各コードの存在理由が不明瞭であるケースが多いです。ファンクションごとにコメントを書く習慣をつけて、トラブルを未然に回避しましょう。

2. プロジェクトごとに作業手順書を作成する

作業手順書とは、Webプロジェクトの作業プロセスを表したドキュメントです。「ジャーナル（履歴）」とも呼ばれます。

たとえば

• Webサイトが正しく機能しなくなった
• Webサイトに新しい機能が必要になった

といった場面で、作業手順書が残されていることで対処方法を洗い出せます。

またデザインや開発手法が進化していった結果、過去と現在でアプローチが変化する可能性もあるでしょう。そんなときこそ、過去の構築プロセスを作業手順書に残しておくことで、トラブルシューティングをスムーズに行えるのです。

どの部分の作業手順書を作れば良いか分からない場合は、Webサイトでもっともユニークな部分から着手しましょう。たとえば独自に作成したテンプレートやコードスニペット、スタイルは作業手順書に残しておきたい対象です。またサーバに関する事項は必ず記録しておきましょう。

3. コードスニペットのライブラリを作成する

再利用可能なコードスニペットは、再びイチから作り直す必要はありません。コードスニペットのライブラリを作成し、いつでも再利用できるようにしておきましょう。たとえ新しいプロジェクトのニーズに合致しなくても、再利用可能なコードスニペットを残しておけばカスタマイズの土台となります。

大量のコードスニペットを整理するには『GitHub』のリポジトリがおすすめです。コードの分類やバージョン管理に役立ちます。リポジトリを別のサービスと連携させることも可能。

コードスニペットのライブラリを作る際には、各スニペットをタグ付け、ラベル付けし、分類して管理しましょう。必要なものをスムーズに検索できるようにするため、使用する言語やその目的、関連するアプリケーション（WordPressなど）、関連するライブラリ（React、Vue、Bootstrapなど）を追記しておくのもおすすめです。

おわりに

プロジェクトの構築プロセスを記録しておくことは、ポートフォリオを作ることと同じくらい重要です。

こうした地道な管理は、既にあるWebサイトの構築とトラブルシューティングにおいてヒントになるだけでなく、新しいWebプロジェクトのソリューションにも繋がります。

今回ご紹介した3つの手法を活用して、コードを整理してみてください。What（なにを）、Where（どこで）、When（いつ）、Why（なぜ）を明確にするための工夫が、コードへのアプローチをより効率的してくれるはずです。

（執筆：Eric Karkovack　翻訳：Nakajima Asuka 　編集：Sansui Riho ）