開発者の生産性を解放する: 「ドキュメントレベル」のコードについて学びますか?

インターネット上で根強いジョーク:

プログラマーが最も嫌う 4 つのこと:

コメントを書く

ドキュメントを書く

他の人はコメントを書かない

他の人は文書を書かない

今日は、開発者が「我慢できず、捨てられない」ドキュメントから始めます。

1. 文書化の重要性

高品質の文書は、人々が規範、ポリシー、手順を理解し、遵守するのに役立つ情報を記録および伝達するための効果的なツールです。また、意思決定や問題解決をサポートするための参考および証拠としても機能します。書面による記録により、人々は知識を長期間保存し、共有することができます。さらに、適切な文書化により生産性が向上し、誤解や間違いが減少します。結論として、文書は私生活と仕事において重要な役割を果たし、組織の持続可能な発展にとって極めて重要です。

高品質のドキュメントは組織やチームにとって多くのメリットをもたらします。

まず、ドキュメントによってコードと API が理解しやすくなり、エラーの可能性が減ります。

第 2 に、文書化により、チームメンバーは目標にさらに集中し、問題を迅速に解決できるようになります。

また、ドキュメント化により、一部の手動作業が容易になります。

さらに、新しいメンバーが参加した場合は、ドキュメントを使用することで、より迅速にチームに統合できるようになります。

ドキュメントの作成には大きな利点の遅れがありますが、テストと異なり、テストケースを実行すると、それが正しいかどうかがすぐにわかり、その値がすぐに反映されます。
文書を作成すると、その重要性が時間の経過とともに明らかになります。書くのは一度だけかもしれませんが、何度も、何百回、さらには何千回も読まれることになります。

優れた文書は、将来次の質問に答えることができます。
•なぜ当時そのような決定が下されたのですか?
•コードがこのように実装されているのはなぜですか?
•このプロジェクトにはどのようなコンセプトが組み込まれていますか？
•...
ドキュメントを作成することは、作成者にとっても大きなメリットがあります。
• API 設計の標準化に役立ちます: ドキュメントを作成することは API を検討するプロセスであり、ドキュメントを作成することにより、API 設計が合理的で包括的であるかどうかを考えることができます。API を言葉で正確に説明できない場合、現在の API 設計が適切であると言うのは合理的ではありません。
•ドキュメントは、コードを提示するもう 1 つの方法でもあります。たとえば、一度書いたコードを 2 年後にもう一度見た場合、コメントとドキュメントがあれば、コードをすぐに理解できます。
•コードの専門性を向上させる: API に完全なドキュメントがある限り、それは適切に設計された API であると誰もが感じています。この感覚が完全に正しいわけではありませんが、この 2 つは確かに切り離せないものであり、多くの人にとって、ドキュメントの完全性は製品のプロ意識を測る指標にもなっています。
•繰り返される質問の不必要な中断を防ぐ: 一部の質問は文書に直接記録できるため、誰かが質問してきたときに、説明を繰り返さずに文書を直接見ることができます。。

2. ほとんどの人が文書を書くのが嫌いな理由

なぜ多くの人が文書を書く習慣を身につけていないのでしょうか? 結局のところ、問題が解決されてから長い時間が経った後では、文書化が非常に重要になります。

ドキュメント収入の遅れの理由には、先に述べた以外にも以下の要因があります。

•多くのエンジニアは、仕事だけでなく、コーディングとライティングを分離することに慣れており、両者はまったく無関係なタスクであると考えるため、多くの人がコードに注目し、ドキュメントの重要性を無視することになります。

•また、多くのエンジニアは自分が文章を書くのが得意ではないと考えており、単に書かないことを選択しています。しかし、これは怠け者の言い訳にすぎません。実際、文書を書くのに華麗な修辞や鮮やかな言葉は必要ありません。問題を明確にするだけで十分です。

•場合によっては、ツールを使用できないことが文書作成に影響を与えることもあります。ドキュメント作成を開発ワークフローに統合する高品質の作成ツールがなければ、作成の負担は増加します。

• ほとんどの人は、ドキュメントを書くことも仕事の負担であると考えています。ドキュメントを書くことはおろか、コードを書く時間ももうありません。これは実際には間違った概念です。ドキュメントの作成にはある程度の先行投資が必要になる場合がありますが、その後のコードのメンテナンスにかかるコストを大幅に削減できます。木を切る前にナイフを研ぐという原理は誰でも理解できると思います。

3. AI ツールが役立つ

「ドキュメントレベル」のコードを生成できる AI プログラミングツールがあれば、コメントやドキュメントを書くことができない、または書きたくないというほとんどの開発者の大きな問題を解決できるでしょうか?

Feisuan の SoFlu ソフトウェアロボットの重要な部分として、FuncGPT AI ジェネレーターはあらゆるタイプの関数の作成をサポートします。FuncGPT AI ジェネレーターは、自然言語を使用して Java 関数の要件を記述し、高品質で可読性の高い Java 関数コードをリアルタイムで生成します。生成されたコードは、IDEA に直接コピーすることも、Java の全自動開発ツールの関数ライブラリにワンクリックでインポートすることもできます。

FuncGPT (Hui 関数) は、次のコードの問題をうまく解決できます。

1.コード仕様: Java 文法およびコード仕様に準拠した関数コードを生成します。生成されたコードは読みやすく、理解しやすくなります。

2.コードの再利用:生成された関数コードは、再利用可能なベストプラクティスを使用する傾向があります。冗長なコードを削減し、コードの保守性を向上させることができます。

3.コードコメント:生成されたコードには、開発エンジニアが関数の目的と入出力を理解するのに役立つ明確なコードコメントが含まれます。良いコメントは後のメンテナンスにとって非常に重要です。

4.コード構造: 生成されるコードは、適切なコード構造を使用し、過度に長い関数や過度のネストを避ける傾向があります。これにより、コードの可読性と保守性が向上します。

5.コードのデバッグ作業を大幅に削減:生成されたコードは大規模な共同トレーニングを通じてトレーニングされるため、より正確で安定したコードが生成され、コードエラーによるデバッグ作業が軽減されます。

例として、タスク管理システムで Java 関数を使用してタスクの残り時間を計算する機能を実装します。

//クラス名: DateUtils

//関数名：calculateDateDifference

//関数 function: 2 つの日付間の日数の差を計算します。

// POM依存関係パッケージ:

// <依存関係>

// <groupId>joda-time</groupId>

// <artifactId>joda-time</artifactId>

// <バージョン>2.10.10</バージョン>

// </依存関係>

org.joda.time.DateTime をインポートします。

org.joda.time.Days をインポートします。

パブリッククラス DateUtils {

    /**

     * 2 つの日付間の日数の差を計算します。

     * @param startTime開始時刻

     * @param endTime終了時刻

     * @return 日数の差の文字列

     */

    public static String CalculateDateDifference(DateTime startTime, DateTime endTime, String format) {

        Days days = Days.daysBetween(startTime, endTime); // Joda-Time を使用して日数の差を計算します

        int 差分 = days.getDays();

        文字列の結果。

        スイッチ (フォーマット) {

            「天」の場合：

                結果 = 差 + "天";

                壊す;

            場合「いつ」:

                結果 = 差 * 24 + "時間";

                壊す;

            ケース「フェン」:

                結果 = 差 * 24 * 60 + "分";

                壊す;

            デフォルト：

                throw new IllegalArgumentException("Invalid format"); //形式が無効な場合は例外をスローします

        }

        結果を返します。

    }

}

//関数の例

// 2 つの日付間の日数の差を計算する例

//入力パラメータ: startTime、開始時刻、タイプは DateTime、endTime、終了時刻、タイプは DateTime、フォーマット、フォーマット文字、タイプは String

//出力パラメータ: 結果、日数の差の文字列

//呼び出し例:

// DateTime startTime = new DateTime(2022, 1, 1, 0, 0); //開始時刻オブジェクトを作成します

// DateTime endTime = new DateTime(2022, 1, 5, 0, 0); //終了時刻オブジェクトを作成する

// 文字列結果 = DateUtils.calculateDateDifference(startTime, endTime, "天");

// System.out.println(result);

//出力結果: たとえば、2022 年 1 月 1 日と 2022 年 1 月 5 日の差の日数を計算します: 4

//出力結果は次のようになります: 4 日

分析を通じて見つけるのは難しくありません。

1.注釈: コードの上に XML 注釈があり、このクラスが joda-time ライブラリバージョン 2.10.10 を必要とすることを示しています。これは、コードの依存関係と実行時環境を理解するために非常に重要です。

2.読みやすさ: 関数名の命名は明確で説明的であり、関数の主な機能を示しています。パラメーター名も明確なので、各パラメーターが何をするのかを理解しやすくなっています。各コードブロック (インポートステートメントや関数本体など) は、コードを読みやすくするために適切なインデントとスペースを使用します。

3.コードの品質:

Days.daysBetween メソッドを使用して 2 つの日付間の日数の差を計算することをお勧めします。これにより、時差の計算を直接実行することで発生する可能性のある問題 (夏時間、タイムゾーンなど) を回避できます。
スイッチケース構造は、さまざまなフォーマットのリクエストを処理するために使用され、さまざまなニーズに柔軟に対応できます。無効な形式の入力の場合、メソッドは例外の処理を示すIllegalArgumentExceptionをスローします。
コードを理解し、保守しやすくするために、合理的な変数名とメソッド名が使用されています。
合理的なコメントは、コードの機能とパラメーターの役割を説明するために使用されます。
コードではマジックナンバーやハードコーディングされた値は使用されず、代わりに適切な定数または変数が使用されます。
入力パラメーターの型はDateTimeであるため、関数は非常に多用途になり、さまざまな時刻形式を受け入れることができます。
戻り値の型はStringなので、関数の出力は読みやすく、表示しやすくなります。

FuncGPT がもたらす効率的で高品質な開発エクスペリエンスも体験したい場合は、無料でダウンロードして使用してください: https://c.suo.nz/74QvS

開発者の生産性を解放する: 「ドキュメントレベル」のコードについて学びますか?

おすすめ