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 )

※Workship MAGAZINEでは日々情報の更新に努めておりますが、掲載内容は最新のものと異なる可能性があります。当該情報について、その有用性、適合性、完全性、正確性、安全性、合法性、最新性等について、いかなる保証もするものではありません。修正の必要に気づかれた場合は、サイト下の問い合わせ窓口よりお知らせください。

30,000人以上が使う日本最大級のお仕事マッチングサービス『Workship』

「フリーランスとして、もっと大きな仕事にかかわりたいな……」
「企業で働いてるけど、副業でキャリアを広げていきたいな……」
「報酬が低くて疲弊している。もっと稼げるお仕事ないかな……」

フリーランス・複業・副業向けお仕事マッチングサービス『Workship(ワークシップ)』が、そんな悩みを解決します!

  • 30,000人以上のフリーランス、パラレルワーカーが登録
  • 朝日新聞社、mixi、リクルートなど人気企業も多数登録
  • 公開中の募集のうち60%以上がリモートOKのお仕事
  • 土日、週1、フルタイムなどさまざまな働き方あり
  • 時給1,500円〜10,000円の高単価案件のみ掲載
  • お仕事成約でお祝い金10,000円プレゼント!

登録から案件獲得まで、利用料は一切かかりません。一度詳細をのぞいてみませんか?

>フリーランス・複業・副業ワーカーの方はこちら

>法人の方はこちら

Workship CTA

SHARE

RELATED

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