コードドキュメントの値

Posted on by admin

コードドキュメントは、コードベースが何をするのか、どのように使用できるのかを説明する、わかりやすい画像と書かれた説明の集

関数やブロックの上の簡単な説明コメント、または規範的なスタイルのdos-and-don’ts、アプリケーションの各部分の概要、および最も一般的なタイプのコー

あなたのコードをコメントし、平易な言語でコードベースのgnarlier領域を概説する意識的な決定を下すときは、これら二つの両極端の間に幸せな媒体を見つ

なぜあなたのコードを文書化するのですか？

なぜコードを書くのではなく、あなたのコードについて書くのに苦労するのですか？ それはとにかくより生産的ではないでしょうか？

恩着せがましいwonka meme

精神的なセーブポイント

ドキュメントは、あなたが最終的に一日の終わりに何が起こっているのかを取得し、勢いを失いたくな よく文書化されたコードは、明日の朝（または今から数ヶ月）に戻ってダイビングする必要があるときに、スピードを上げるのに多くの時間を取る必要がな

文書化されたコードが再利用される

使用されているライブラリと未使用のライブラリの違いは、多くの場合、そのドキュメントに帰着します。

誰が文書化されていないオープンソースライブラリを使用するか、文書化されていないプロジェクトに貢献したいですか？ ほとんど誰もいません。

ほとんどの場合、docsを持つあまり強力でないライブラリを使用したいと思います。 どうして？ ドキュメントには、コードベースに関する他の情報ポイントが伝達されるためです。 開発者は、プロジェクトが平易な言葉でそれについて書くための時間とエネルギーの価値があると信じているので、興味のある人はすぐに始めて、それがどのように機能するか、そしてなぜ重要な決定が下されたのかを学ぶことができます。

あなたの好きな言語で、新しく、興味深く、よく文書化されたプロジェクトを見つけることは非常に刺激的で楽しいことができます。 文書化されていないコードライブラリを使用し、潜在的に一見ビザンチンのコードベースに貢献する必要があるという極端な選択肢を見てみましょう。.. それは右、かなり痛いですね？

では、なぜ独自のコードを文書化していないのですか？

コードを文書化することは、良いコードを書くことの一部です

良いコードの基礎は、理解しやすく読みやすい文書化によって達成される保守性です。

コードを文書化するには複数の方法があります:

  • 変数と関数の適切な名前の選択
  • 将来の読者にコンテキストを与えるためにコード内に簡単なコメントを残す
  • シーケンスやエンティティ関係図などの例示的な画像を追加する
  • Apiドキュメントを提供し、各クラス、メソッド、引数、戻り値を記述する
  • TypeScript(types as documentation)などの静的に型付けされた言語を使用する
  • )

2つの例を比較してください

バックエンドAPIからデータを取得し、それを「取り込み」しているとしましょう-それをより便利な形状に変換します。 フロントエンドUI。 ここでは2つの可能な解決策の最初のものです。

// wdgt.jsexport const converter = (w) => { wdgtHdr = { name: w.nm, id: w.id, ts: w.lastTS } wdgtDtl = { dtlId: w.dtlId, dtlName: w.dtlNm, openTS: w.oTS, closeTS: w.cTS } wdgtRev = w.revs.map((r) => { const { note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = r const rr = { assocId: prsn1Id, assoc: `${prsn1Fn} ${prsn1Ln}`, amount: amt, note: note, revTS: cTS, } return rr } return { wdgtHdr, wdgtDtl, wdgtRev }}

上記のコードは痛みを伴う可能性があります。 名前で見ると、これはwをパラメータとして取るある種のコンバータであることがわかります。

ヘッダー、おそらく詳細、およびrevsと呼ばれるものを返すように見えます。 Revsはどこから来たのですか？ もちろん、入ってくる変数名note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTSについての詳細はありません。.. またはそこにありますか？ rrはreturned revの略ですか？ 誰が言うことができます。

2番目の例を見てみましょう。

// widget_utils.ts// widgetConverter :: widgetRespDTO -> widgetexport const widgetConverter = (wResp: widgetRespDTO): Widget => { const widgetHeader: WidgetHeader = { name: wResp.nm, id: wResp.Id, ts: wResp.lastTS), // timestamp } const widgetDetail: WidgetDetail = { id: wResp.widgetId, name: wResp.dtlNm, openTS: wResp.oTS, // timestamp closeTS: wResp.cTS // timestamp } // is nested inside of WidgetRespDTO // .map -> const widgetRevisions: ReadonlyArray<WidgetRevision> = wResp.revs.map((wRevs: WidgetRevisionsRespDTO): WidgetRevision => { // how that other team names their variables...! const { cmt, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = wRevs const comment: string = cmt const associateId: string = prsn1Id const associateName: string = `${prsn1Fn} ${prsn1Ln}` const amount: number = amt const revisionTS: number = cTS // unix timestamp, and "closeTS" fyi return { associateId, associateName, amount, comment, revisionTS, } } return { widgetHeader, widgetDetail, widgetRevisions, }}

うわー、どのように違う！ この関数はutilファイル内にあるため、メインファイルはすでに雑然としていません。 また、普通のJavaScriptの代わりにTypeScriptで書かれているので、私たちを導くのに役立つ型定義の利点があります。

私たちはwidgetRespDTOをwidgetに変換しています。wRespが何であるかについての完全な知識を持っています。 私たちはwidgetHeaderとwidgetDetailを作成していますが、それは見やすいです。 私たちはまた、oTSとcTSが何であるかを理解しています。 WidgetRevisionsRespDTOがWidgetRespDTOの内部にネストされていることを伝えることができます。

誰かが非常に親切に入ってくる変数の名前を変更したので、このコードを見ている人は誰もが彼らが何であるかを知っています。 最後に、Widgetは、先頭で指定された戻り値の型Widgetと一致する必要があるため、返された{widgetHeader, widgetDetail, widgetRevisions}オブジェクトで構成されている必要があります。

どのコードを使用した方が良いですか？

誰が利益を得るのですか？

よく文書化されたコードは多くの人々に利益をもたらします：

ジュニア開発者

それは平易な言語で理解しやすいので、ドキュメントはジュニア開発者や新しいチームメンバーがコードベースに飛び込むことに自信を持って感じるのに役立ちます。 これにより、タスクがあまりにも早く複雑になるため、欲求不満やタスクの早期放棄を防ぎます。

ジュニア開発者が自分のコードを他の人と共有したり、コードをよりよく理解したりできるように、独自のドキュメントを書くことも役立ちます。

上級開発者

今すぐ文書化する時間を取ることで、上級開発者は将来自分のコードを他の人に説明する時間を少なくすることができます。

より複雑なコードを書くこともできます。 平易な言語の文書は、他の人が内部の仕組みを理解することなく、ブラックボックスのようにそれを使用することができます。

Teams&オープンソースプロジェクト

人事異動はプロジェクトに大きな減速をもたらす可能性があります。 最新かつ十分に文書化されたコードは、このような減速に対する保険として機能し、残りのチームメンバーが一歩後退し、高いレベルからコードをレビューし、前進する最良の行動方針を決定し、必要に応じて新入社員をオンボードすることができます。

あなた

コードを文書化するときは、それを要約する必要があります。 適切に要約するためには、同時にあなたの頭の中でさまざまな部分を保持し、それを理解することができなければなりません。 ドキュメントを書いたり貢献したりすることは、コードベースを本当に理解し、大きな貢献をし、偉大なチームの偉大な部分のように感じるための近道です。

優れたドキュメントは、コーディングの経験を枯渇させることができます

プログラマとして、クリーンで簡潔なコードを書くための鍵として、Don’t Repeat Yourselfの原則を聞いたことがあるでしょう。 同じコードブロックを何度も繰り返すのではなく、一度記述してアプリケーション全体で使用できる関数を記述してください。

同じように、あなたとあなたのチームは同様の問題に遭遇し、それらを解決しようとするたびに車輪を再発明するべきではありません。 たとえば、あなたの同僚の一人を聞いたことがあるか、自分自身が言っていることを見つけましたか：

“ああ、私はこれに非常に似たものを解決しましたが、.. どこかに書いた方がいいんじゃないかな?”

その後、同じStack Overflowスレッドを何度も何度もスキャンしています。

DRY原則の精神に従って、問題が発生するたびに使用できる文書を書くことによって、この悲しみを自分自身と同僚を救いましょう！ これは、あなたとあなたのチームの他の人が時間を節約し、より簡単で、より管理しやすく、より効率的なコードを書くのにより効果的になります。

コード文書、またはその欠如はあなたにどのような影響を与えましたか？

コメントを残す

メールアドレスが公開されることはありません。