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

Documenting Web Projects

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

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

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

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

Documenting Web Projects

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

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

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

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

Documenting Web Projects

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

たとえば

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

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

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

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

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

Documenting Web Projects

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

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

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

おわりに

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

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

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

(執筆:Eric Karkovack 翻訳:Nakajima Asuka  編集:Sansui Riho )

SHARE

RELATED

  • お問い合わせ
  • お問い合わせ
  • お問い合わせ