コーヒーブレイク#79。Java 開発者が成功を妨げる 10 の間違い。意味のあるコード コメントを書くための開発者ガイド

Java 開発者が成功を妨げる 10 の間違い

出典: Dev.to 私の経験に基づいて、開発者の成功を妨げる 10 の間違いのリストを作成しました。

1.単体テストを書かない

単体テストを作成しない開発者は、コード内でより多くの間違いを犯します。これは製品の不安定性と顧客の不満につながります。

2. コードを手動でチェックしない

コードを単体テストで完全にカバーしたとしても、何かを見落としている可能性は依然としてあります。レビューのためにコードを送信する前に、コードを手動でテストすることを常にお勧めします。これにより、開発段階でエラーを検出できます。

3. 彼らは、「そんなことは決して起こらない」と考えています。

開発者は、特定のシナリオが決して起こらないと考えて、新しいコードを作成するときに間違いを犯すことがよくあります。結局、彼らは間違っていたことが分かります。コードが実行される可能性のあるすべてのシナリオを処理します。防御的なプログラミング手法がこれに役立ちます。

4. フィードバックを受け取らない

他の開発者やユーザーからのフィードバックを定期的に求めます。あなたの意見を同僚と共有してください。

5. コードの機能をチェックしません。

多くの場合、開発者はコードを作成しますが、その機能をチェックしません。その結果、コードが運用環境に到達すると、さまざまな問題が発生します。

6. 長い手続き型コードを書く

多くのロジックを含む長いメソッドを記述するのは非常に簡単です。これを行うことで、プログラマは同じロジックをさまざまな場所に実装します。多数の小さなメソッドを含むプロジェクトでは、コードの再利用が大幅に向上し、保守がはるかに簡単になります。

7. 彼らはツールを知りません

ツールは手の延長です。それらをよく知れば知るほど、生産性が向上します。使用している IDE についてよく知っている必要があります。簡単なコマンドを学びましょう。さらに生産性を高めるのに役立つコマンドが常にあります。IntelliJ IDEA では、これらは Sonar Lint、Spot bugs、および Code Metrics です。

8. コードの問題を無視する

最も成功した製品に取り組む開発者は、常にコードを変更します。コードをリファクタリングすることを恐れないでください。コードが単体テストされている場合、回帰の可能性はほとんどありません。開発者は問題のあるコードを無視することがよくあります。開発者には、アプリケーションを良好な状態に維持する責任があります。このため、見つかった問題はすべて修正してください。

9. 彼らは結果を理解せずにコードを書きます。

開発者は、その結果を理解せずに、コードを変更して運用環境にリリースすることは絶対に行わないでください。コードは、指定されたテスト値に対して正しい結果を生成する可能性があります。ただし、これが予期しない結果をもたらし、深刻な問題を引き起こす可能性のあるシナリオが存在する可能性があります。「予測できない」コーディングは、開発者が完全に理解していないライブラリの関数を使用するときによく発生します。これは、開発者が解決策を理解せずに問題を修正した場合にも発生する可能性があります。

10. 助けを求めないでください

開発者はあまり社交的な人ではありません。彼らは自分たちで問題を解決することを好みます。しかし、開発者自身が最初から最後まで製品を作る時代は終わりました。ソフトウェア開発はチームで行う活動です。プログラミング中に問題が発生した場合は、自分で解決してみてください。ただし、解決策が見つからない場合でも、時間を無駄にしないでください。同僚の中に、すでに同じ問題に遭遇し、解決策を知っている人がいる可能性が高くなります。これにより時間が節約され、生産性が向上します。

意味のあるコード コメントを書くための開発者ガイド

出典: Stepsize ほとんどの場合、同じプロジェクトまたはコードベースに取り組んでいるのはあなただけではありません。これは、他の人があなたのコードを理解する必要があることを意味します。これはコードのコメントにも当てはまります。開発者は多くの文脈を持たずに「簡単で汚い」コメントを書くことがよくあり、作成者が何を言おうとしているのか同僚を混乱させてしまいます。これは悪い習慣であり、明確さよりも混乱を招きます。 明確なコード コメントがあると、他の開発者に役立ちます。関数、その理論的根拠、入力、出力を説明するコード コメントにより、他の開発者の学習プロセスが高速化されます。一方、コードのコメントは、「コメントを書く価値があるのか​​?」という疑問につながります。開発者のかなりのグループが、コード コメントを書くことに反対しています。その理由は、彼らの意見では、コードが一目瞭然だからです。他の開発者がコードを見てその目的を理解できない場合、それは悪いコードです。おそらくこれは真実でしょう。ただし、コードをコメントアウトするのに必要なわずかな労力と、それによってもたらされる潜在的な利点について考えてみましょう。コード コメントは、開発者、特に若手のオンボーディング プロセスをスピードアップするために重要です。さまざまな種類のコード コメントを見てみましょう。

1. ドキュメントに関するコメント。

このようなコメントの主な目的は、ファイルまたはコンポーネントの目的を迅速に明確にすることです。コンポーネントの動作を理解するためにコンポーネントのコード全体を読む代わりに、「index」ファイルの先頭にコード コメントを追加できます。これは、このコンポーネントの機能を説明するのに役立ちます。コードが少し乱雑になるため、私はこの種のコメントはあまり好きではありません。このようなタイプのアーキテクチャに関するコメントは、プロジェクトのアーキテクチャを一元的に保守および議論できる内部ドキュメントに含めるべきだと思います。ただし、オープンソース プロジェクトにはそれらが本当に必要です。

2. 関数に関するコメント。

これは最も便利なタイプのコメントです。関数の目的、パラメーター、出力について説明します。

/**
 * @desc Creates a welcome message
 */
function sayHello(name) {
    return `Hello ${name}`;
}

3. 論理的なコメント。

これらは、複雑なコード パスを明確にするための関数内のコメントです。ご想像のとおり、このようなコメントの存在は、コードが複雑すぎることを示しています。さらに、論理的なコメントには詳細な情報が多すぎることがよくあります。詳細レベルを高くすると、さらに混乱が生じ、コードの可読性が低下します。以下は、詳細すぎるコード コメントの例です。

let date = new Date(); // store today's date to calculate the elapsed time

コードのコメント: コメントに関する 4 つのベスト プラクティス

1. コードの注釈またはタグを使用する

多くのプログラミング言語では、コードのコメント化の標準が定義されています。Java はJavadocを使用しますが、JavaScript はJSDocコード コメント システムを使用します。これは多くのドキュメント ツールでサポートされています。関数の場合は、次のコード タグを含める必要があります。

• @desc - 関数の説明
• @param - 関数が受け入れるすべての入力パラメータ。入力タイプを必ず指定してください。
• @returns - 返された出力。出力タイプを必ず指定してください。
• @throws は、関数がスローできるエラーのタイプです。
• @example - 入力と予想される出力を示す 1 つ以上の例。

次に、チャンク関数のLodash コードの例を示します。

/**
 * Creates an array of elements split into groups the length of `size`.
 * If `array` can't be split evenly, the final chunk will be the remaining
 * elements.
 *
 * @since 3.0.0
 * @category Array
 * @param {Array} array The array to process.
 * @param {number} [size=1] The length of each chunk
 * @returns {Array} Returns the new array of chunks.
 * @example
 *
 * chunk(['a', 'b', 'c', 'd'], 2)
 * // => [['a', 'b'], ['c', 'd']]
 *
 * chunk(['a', 'b', 'c', 'd'], 3)
 * // => [['a', 'b', 'c'], ['d']]
 */
function chunk(array, size = 1) {
  // logic
}

2. 自分の行動の理由を説明する

多くの開発者は、コメントを使用してコードの動作を説明します。その際には、特定の機能またはコンポーネントを作成した理由を必ず含めてください。この情報はコンテキストと呼ばれます。コンテキストは、機能またはコンポーネントの背後にある設計上の決定について開発者に詳細な情報を提供するために重要です。他の開発者が機能やコンポーネントに変更を加えたい場合、コンテキストは非常に重要です。以下に、コンテキストなしでコードをコメントする悪い例を示します。

/**
 * Sets the label property of a new form.
 *
 * @param label text for label of form
 */
function setFormLabel(label) {
    // logic
}

3. 他のドキュメントやコメントにリンクしないでください。

機能やコンポーネントを説明する他のコード コメントや内部文書にリンクすることはお勧めできません。

/**
 * Sets the label property of a new form.
 *
 * @see {@link https://myinternaldocument.com}
 */
function setFormLabel(label) {
    // logic
}

4. コーディング中にコメントを書く

これは明白に思えるかもしれませんが、多くの開発者 (私も含めて) がこのルールを無視しています。コメントを後で残すのは良くありません。自分が書いたロジックの一部を忘れてしまう可能性があり、コード コメントの品質が低下する可能性があります。これは、同じプル リクエストに数日間取り組んでいる場合に特に当てはまります。機能またはモジュールを終了した直後にコメントを書くことをお勧めします。コードのコメントはできるだけ短くしてください。コメントの作成には、コード自体の作成よりも多くの時間を費やす必要はありません。