私のクライアントは、私の現在のプロジェクトでコメントの25％を望んでいます。
ここでジュニア開発者。
現在、自分の会社の大口顧客向けのWebアプリケーションの開発に単独で取り組んでいます。先月始めました。クライアントは、各ソフトウェアプロジェクトに少なくとも25％のコメントを求めています。
私は以前のアプリケーションのコードをチェックしました、そしてここに私の観察があります：
- 各ファイルはコメントブロックで始まります（パッケージ、最終更新日、会社名、著作権）
すべての変数は、その名前
// nameOfCustomer public String nameOfCustomerでコメント化されていますすべてのゲッターとセッターはコメントされています
- 役に立つコメントはほとんどありません
開発者は、品質と有用性に関係なく、25％のしきい値に達するためにできるだけ多くのコメントを配置するだけのようです。私の会社は、「クライアントが望むように私たちはそれをする」と言っています。
これについてクライアントと直接話をしませんでした。これまでの私の議論はここにあります：
- 読み書きする無駄な行（時間の無駄）
- コメントが更新されない場合がある（混乱の原因）
- 開発者は実際に役立つコメントを使用または信頼する可能性が低くなります
この問題についてのあなたのアドバイスは何ですか？どのように対処すればよいですか？
ここでの他のすべての回答とコメントは本当に私をループに入れました、なぜならそれらは私の最初の反応にとても反対であり、私の同僚で私が見た態度にとても反対です。だから 異議を唱える声 のためだけに別のアプローチを説明したいと思います。
この回答の基本原則は、「お客様を喜ばせる」です。顧客を喜ばせるということは、期待に応えることだけではありません。それは、彼らの要求を深く理解することで、彼らが彼らの意味する方法で彼らが言うことを解釈し、彼らが要求するものを超えて提供することを意味します。他の回答は、悪意のあるコンプライアンスの原則に導かれているように見えます。さらに、リピーターを獲得するには悪い方法であるため、疑わしいビジネス慣行です。
私がクライアントに「25％のコメントが欲しい」と言うのを聞くと、それが対話の始まりです。私にとっては、他の回答のように「特定の構文カテゴリにランダム性を追加してほしい」ではなく、「このコードベースの初心者がすぐに立ち上がって実行できるように、多くの説明文が欲しい」という意味があることは明らかです。それを取っているように見えます。そして、私はその要求を真剣に受け止め、多くの説明的で役立つコメントを書き、コードの構造に新参者を導き、意外なエンジニアリングの決定を指摘し、それらに入った理由を概説し、高レベルの英語を与えるつもりです複雑なコードセクションの説明（たとえ驚きがなくても）。この意図と理解は、議論の開始点です-つまり、私たちが話し始める前です。私にとって、リクエストの意味は非常に明確であるため、その説明は必要ありません。しかし、あなたにとってそれが不明確な場合は、もちろん彼らと一緒にチェックインする必要があります！
さて、それが開始点である場合、ダイアログはどこに行きますか？ダイアログの次の部分は次のようになります。
- これは、おそらくプロジェクトの第2フェーズで、彼らが作業に関心のあるツールの作成を超えた、さらに深刻な作業になると思います。このプロセスとそれが追加の作業である理由を説明するのに数分の議論になるかもしれませんが、プロのプログラマーとしてあなたに期待しているので、ここでは省略します知っている良いコメントをするのがどれほど難しいか。
- 「深刻な追加の努力」とは、より長い時間の予算とより大きな通貨の予算が必要になる可能性があることを意味します。 または機能の予算を減らす必要があるかもしれません。 またはコメントの質と量について妥協する必要があるかもしれません。この部分は少しの交渉になるでしょう。しかし、私の意見では、この追加作業を行うためのコストについては非常に前向きであり、クライアントにとってこれらのコストを喜んで引き受けることができるような重要な機能であることを確認する必要があります。そして、もしそうなら-すごい！あなたは余分な時間とお金を得て、彼らは質の高いコメントを受け取ります。誰もが勝つ。そして、コメント機能がそれほど重要ではないことが判明した場合、ウィジェットをいじくる能力を失ったり、締め切りを20x6のGranuaryに遅らせたりしても、全員が再び勝利し、製品を手に入れます。高品質のコメントを作成するために余分な労力を費やす必要はありません。
ここで、ダイアログができないべきだと思います：
- 低品質のコメントでクライアントを脅迫しないでください。彼らがあなたが彼らが費やしたい努力のレベルと彼らがお金を払う用意があることを選ぶ手助けをさせましょう。 25％のコメントを約束しないでください。その後、プロジェクトの構築後にランダム性を自動生成することで、この約束を果たすつもりであることを伝えます。
- 計画を隠さないでください。 25％のコメントを約束しないでください。そして、何をしようとしているのかを知らせずにランダム性を自動生成します。 いつ気づいた場合（そうでない場合）、両方とも大きな時間を失う：彼らは得た製品に不満であり、否定的な言葉を得る口。
- 彼らがコメントを望んでいないと彼らに納得させようとしないでください。彼らは明らかにコメントを求めています。さまざまなアプローチのトレードオフについて話し合う：はい！コードベースを新しく使いやすくする別の方法について話し合います。彼らが何を望んでいるのか分からないことを伝えてください：ええ、いいえ。あなたは彼らと協力して彼らが望むものを手に入れたいのです。それが何であるかを理解し、彼らが承認した予算で彼らにそれを提供する最善の方法を見つけ、彼らが持っているリソースが不十分である場合、彼らが最も気にする機能を優先します。
- コメントを書くのがいかに難しいかについて言い訳をしないでください。コードを書くのは難しいです。コードのデバッグは困難です。コメントを書くのは難しいです。それが簡単だったら、彼らはあなたを雇っていないでしょう。苦情をスキップして、彼らが気になるポイント、つまり必要な追加の労力が彼らにどのように影響するかについてまっすぐに進みます。
お客様は王様です。したがって、請負業者として、クライアントが品質基準として定義したものは何でも満たす必要があります。または、あなたは外に出る危険があります。
これが言われていることは、（ここでは貧弱な）品質基準がどのように定義されているかが非常に重要です：
契約上の品質基準：提供されるコードは準拠している必要があります。そうでない場合、契約違反となります。選択の余地ない。
正式な企業の品質基準：たとえ完全に機能しても、準拠していないコードは多くの人々から質の悪いものと見なされ、すべてをより良い慣行に変換する前に古くなるでしょう。さらに悪いことに、よく知られているツールを使用して、そのような品質メトリックを自動化および正当化できます（例： ソナーキューブ ）。ほとんど選択の余地はありません。
クライアント側で数人が定義したアドホック基準。ここで議論をすることができます。希望がある ：-）
この最後のケースでは、ある程度の柔軟性があり、外交的に要点を述べることができます。ここに顧客の基準に反するいくつかの議論があります：
- 生産性の問題：コーディングは2回行われます（英語で1回、コードで1回）。
- 精度の問題：コードで変更を行う場合は、コメントで行う必要があります。そうしないと、コメントが役に立たなくなる可能性があります。
- リファクタリングの問題：リファクタリングツールはコメント内の変数名を処理しないため。
- リスクの問題：コメントのあいまいさ（または陳腐化）は、混乱を引き起こし、バグを増やすリスクを引き起こす可能性があります。
- 量は質ではない
- StackOverflowに関する役に立たないコメントのこの面白いコレクション 。
- この記事 は、コメント率が高いことがコードの匂いの兆候である可能性さえあると主張しています。
しかし、悪いことに反対して顧客に立ち向かうのではなく、単により良いアプローチを促進することができるでしょう：
- きれいなコード（この本を顧客に提案してください：コメントと自己文書化コード専用の説得力のあるセクションがあります）。
- 文書化の実践：把握するのが最も難しいこと、したがって、たとえばクラス間の関係や相互作用などの最も価値のある情報は、別の文書（たとえば、1000のコメントワードではなくUMLの画像）に文書化する方がよいでしょう。
それでも顧客が納得できない場合は、javadocや doxygen などのコメント付きのドキュメントを自動的に生成するツールを使用して、実験的な代替案を提案できます。それに焦点を合わせて、量（コードの25％）から品質（理解しやすいjavadocを生成する）にフォーカスを移してください。
クライアントは、各ソフトウェアプロジェクトに少なくとも25％のコメントを求めています。
クライアントは本当にコメントの25％を望んでいますか、それともクライアントはコードを可能な限り説明的にしたいと考えていますか？
私見、クライアントは自分が何を望んでいるかは知っていますが、何が必要かは知りません。クライアント自体は開発者ではなく、自身の労働者/顧客からフィードバックを受け取るため、クライアントには氷山の上部のみが表示されます。
あなたのクライアントには疑似知識があり、コードを十分に文書化し、簡単かつ安価に保守できるようにしたいと思います。このためのツールはコメントです（彼の心の中で）。
彼と話してみて、自分自身を説明する上手に書かれたコードを含むコードスニペットをいくつか準備し、コメント付きの別の悪いスニペットを準備してください。ほんの数行。必要に応じてこれを表示し、言葉の絵として使用してください。
クライアント/スーパーバイザー/何でも話して、バージョン管理の最新の原則（ファイルの先頭にコメントは必要ありません）とクリーンなコード（私は 本 もお勧めします）およびしたがって、自己説明コードが生成されます。
たぶん、それを十分に示し、クライアントにコメントだけでなくクリーンなコードが必要であることをクライアントに理解させることができれば、あなたとあなたのチームはより優れたコードを書くことができ（コメントがはるかに少ない）、あなたが守るべき優れた開発者であることをすぐに示すことができます。
これは、1行に続いて文字通り「最小文字数の制限に達するためのテキスト」が続く、馬鹿げたスタックオーバーフローの回答を思い出させます。
これが発生した場合、2つのグループの人々が過ちを犯しているという主張をすることができます。
制限を設けた人々—明らかにそれは過剰であり、人為的なノイズを追加せずに適切な形式の情報を送信することを妨げています
されなかったの情報を送信した人は、適切に形成され、システムが実際の物質を追加するように促したときに人工的なノイズを追加しました
時々、質問は両方とも単純ですand on-topicであり、いくつかの言葉よりも言うべきことは多くありません。ただし、これは非常にまれです。ほとんどすべての場合で、言うべき実質の多くがあります。他に何もない場合、それは盲目的に明白である必要があります。文字制限を回避する方法は、ランダムノイズを投稿に単にダンプすることではありません。
あなたが直面しているこのコメントの状況はほとんど同じです。開発者はコメントを要求し、ランダムノイズをコードにダンプすることで実装しました。変数の宣言のすぐ隣にある変数の名前を文書化するのはvandalismです。それは決して起こってはならないことでした。
「しかし、他にどのようにして25％に到達できるでしょうか？」実質の実際のコメントを書くことによって。より多くの単語、より良い単語、最高の単語を使用して、機能の効果を文書化します。あなたの説明を拡大してください。 Edgeケースについて詳しく説明します。
ただし、元のポイントに戻ると、「ソースコードの25％」は非常に恣意的であるため、クライアントも部分的に失敗しています。最終的には、しかし、彼らはクライアントなので、それを最大限に活用します。しかし、私は「最高」を意味します。これまでのように「最悪」ではありません。
この要件について大騒ぎは何ですか。
コードの基本的なdoxygenationだけで、おそらくすでに10％程度です。そして、自分で書いたコメントの5％をもう1つ取りましょう（いくつかはさらに書いていますが、沈黙の誓いを立てていない場合、5％は控えめな見積もりのように見えます）。この時点で約15％です（はい、はい、わかっています。90％の5％は5％未満です。 doxygenが10％未満の場合、おそらくメソッドが非常に長くなります。通常は、それらをより小さな（主にプライベート/保護された）クラスに分割するか、より一般的なヘルパークラスなどを使用することをお勧めします。
ここで、残りのコメントテキストについて-設計上の考慮事項と使用シナリオをクラス/ファイルレベルのコメントに入れます。いくつかのテーブルまたはASCIIアート（またはレンダリング時に見栄えの良いものを生成するdoxygenコード）を用意します。もちろん、あなたのプロジェクトが何であるかはわかりませんが、ダミーのコメント（doxygenationボイラープレート以外）なしでこれを行うことができ、25％近くに到達できると思います。
たとえば、25％ではなく20％の場合は、クライアントがその数値を任意の数値として指定しただけで、問題はないでしょう。とにかく、彼らと話をして、コメントに何が含まれるべきかについて話し合ってください。そして、彼らが満足しているかどうかを確認するために、コメント付きファイルの例を示します。彼らがそれならそれだけです、彼らが何かが足りないと思っているなら、彼らはあなたが足りないものをあなたに伝えます。彼らはあなたに「私たちはどんな可能な追加コメントも提案することはできませんが、私たちはあなたにコメントを追加してほしい」とあなたに言うつもりはありません。
PS-標準のJavaコンテナのコードを見て、70％程度に到達する方法を確認してください...
コードに25％のコメントを含めることは、優れた目標であり、クライアントを幸せにします。 「i + = 1; // iを1ずつ増やす」のような25％のくだらないフィラーコメントを下に書いてください。時間をかけて、便利なコメントを書いてください。そして、やるべきことをするために実際に支払われるという感覚を楽しんでください。とにかく。
これはがらくたの要件であることは誰もが知っています。ここで興味深い質問は
どのように反応しますか？
私は問題を目に見えるようにすることを大いに信じています。ここで私はお金が話しているという事実を使います。
私にこれをするように頼んでください、そして私は確かに言うでしょう、それは私の入札に1％を加えるでしょう。ああ、でも将来のメンテナンス入札には20％加算されます。
なぜ彼らがなぜ私が彼らに良い名前のポイントがコメントの必要性を避けることであるかを教えるのか尋ねるときだけ。
別の方法として、プロジェクトの背後にあるアイデアに迅速に対応するために、想定される資格の定義されたセットを持つメンテナンスプログラマーを獲得することを目的としたドキュメントの作成を提案します。または確かに、25％のコメントを与えることができます。あなた次第。
はい、私はあなたの愚かなルールへの不満を理解しています。私は多くのプログラムを読んだことがあります。
x = x + 1; // add 1 to x
そして私は自分に言います、それがプラス記号の意味です!!うわー、教えてくれてありがとう、知らなかった。
しかし、そうは言っても、顧客は料金を支払います。したがって、あなたは彼らが望むものを彼らに与えます。私が自動車販売店で働いていて、顧客がピックアップトラックを望んでいると言った場合、私は彼が本当にピックアップトラックを必要とするかどうかについて彼と議論せず、彼がそれで運ぶと期待するものについて彼に質問しません。私は彼にピックアップトラックを販売します。
さて、顧客が望んでいることと実際に必要なことは離れているので、私は彼と話し合って、もっと合理的なことに同意するように説得することがあります。うまくいくこともあれば、うまくいかないこともあります。結局、私が彼の考えを変えることができないならば、私は彼が望んでいるものを彼に与えます。彼が後で戻ってきて、「ああ、それは本当に私のビジネス要件を満たしていない」と言った場合は、最初に行うように彼に言ったことを実行するためにさらに課金することができます。顧客とどの程度交渉できるかは、顧客が専門知識をどれだけ信頼しているか、顧客との契約が組織とどのように適合しているか、そして率直に言って、彼らがどれほど強大であるかによって異なります。
それは自分の責任であると想定すると、要件が十分に理解されていないと思ったために契約を失うことは非常にまれなケースです。
あなたの会社が交渉している人々は、この25％のルールを発明した人かもしれないし、そうでないかもしれないことを覚えておいてください。それは上から彼らに課せられたルールかもしれません。
5つの可能な応答が表示されます。
1。上司またはクライアントと交渉している人に、これについて議論するように説得します。オッズはこれは何も達成しないでしょうが、あなたは試すことができます。
二。拒否する。これはおそらくあなたを解雇するでしょう、または会社があなたに同意した場合、あなたは契約を失うことになります。これは非生産的なようです。
三。無駄なコメントを書き込んでスペースを埋めます。これは、コードの内容を繰り返すだけのコメントであり、コードを変更できるプログラマなら2秒で見ることができます。このようなコメントをたくさん見ました。数年前、私は次のようなパラメーターをリストするすべての関数の前にコメントブロックを配置する必要がある会社で働いていました。
/*
GetFoo function
Parameters:
name: String, contains name
num: int, the number
add_date: date, the date added
Returns:
foo code: int
*/
int GetFoo(String name, int num, Date add_date)
これらのコメントを最新に保つ必要があるため、そのようなコメントはメンテナンスの負担であるという異議は無効です。真面目なプログラマーがそれらを見ることはないので、それらを最新に保つ必要はありません。それについて質問がある場合は、チームのすべてのメンバーに、無駄で冗長なコメントは無視する必要があることを明確にしてください。関数のパラメーターが何であるか、またはコード行が何であるかを知りたい場合は、コードを読んで、無用なコメントを見ないでください。
四。価値のない冗長なコメントを追加する場合は、それらを生成するプログラムを作成する価値があるかもしれません。事前に投資する必要がありますが、入力する手間を省くことができます。
私が最初にこのビジネスを始めたとき、私が働いていた会社は、「あなたのためにあなたの文書を書く！すべてのプログラムのための完全な文書！」と宣伝されたプログラムを使用していました。システムでは、すべての変数に基本的に意味のない名前を付け、各変数に意味のある名前を付けたテーブルを用意する必要があったため、基本的に「自動ドキュメンテーション」は、意味のない名前を使用することを強制した意味のない名前に置き換えました。したがって、たとえば、これはCOBOLで機能しました。プログラムには次のような行があります。
MOVE IA010 TO WS124
そして、彼らは言った「ドキュメント」の行を生成します
COPY CUSTOMER NAME IN INPUT RECORD TO CUSTOMER-NAME IN WORKING STORAGE
とにかく、等しく価値のないドキュメントをかなり簡単に生成するプログラムを確実に書くことができます。のような行を読みます
a=b+c
コメントを生成する
// add b to c and save result in a
等。
五。愚かなルールを最大限に活用してください。有用で意味のあるコメントを書いてみてください。ねえ、それは良い練習になるかもしれません。
ああ、ところで、メトリックをいつでもゲームできると付け加えておきます。
かつて雇用主がプログラマーの生産性を週に何行のコードで作成したかで測定するつもりだと言ったことを思い出します。会議でこれを聞かれたとき、私は言った、「すごい！簡単にスコアを上げることができます。これ以上書くことはありません
x=x+4;
代わりに私は書きます：
x=x+1;
x=x+1;
x=x+1;
x=x+1;
ループ？忘れてください。コードを10回コピーして貼り付けます。等。
そこで、ここでコメントの行を数える場合は、各行を短くして、次の行にアイデアを続けます。コメントの内容に変更がある場合は、既存のコメントを更新しないでください。日付を入れて、テキスト全体をコピーし、「更新」と新しい日付を書きます。クライアントが質問した場合は、履歴を維持する必要があると考えたことを伝えます。など.
任意のメトリックは、あまりにも多くのプロジェクトで現実のようです...
これは、コンプライアンスを確実にするために関数が不必要に分割されたり、任意のSLoCの長さを超えたためにファイルが分割されたりするため、Cyclomaticの最大の複雑さなどのダム要件でよく見られます。
コメントはコードに追加し、何が起こっているかを説明する必要があります（コードを繰り返すだけではありません！）。
とはいえ、これが顧客の希望であり、会社が提供することに同意している場合、QAマネージャーが常識を働かせない限り、行き詰まります。
短期的には、あなたが本当にできることは何もありません。それと一緒に行きます。
また、コード内のパッシブなアグレッシブな抗議やばかげたジョークについて、このスレッドで私が目にしているすべての愚かなアイデアを無視する必要があります。
クライアントとの信頼関係を築くと、クライアントはあなたの推論に耳を傾けることができるようになります。これは、かつて影響力を持っていた一人からのばかげた要求であり、社内でのサポートはほとんどないことがわかるでしょう。
いかなる状況でも、クライアントの許可なしにこれに反対するべきではありません。
ここにいる仲間のプログラマーが示した想像力の欠如に失望しています。
クライアントはいくつかの調査をしたようです。彼は、質の高いコードには通常コメントの約25％が含まれていることをどこかで読んだ可能性があります。明らかに、彼は将来のメンテナンスについて気にしています/心配しています。さて、彼はどのようにして契約に結び付けられるべき要件文書でその具体化をしますか？それは簡単ではありません。それも不可能かもしれません。しかし、彼は自分のお金の価値を確実に得たいので、いくつかの品質指標を列挙します。
それは私にはまったく馬鹿げたことやばかげたことには聞こえません。要件を書いた人はおそらくプログラマーではありません。彼らは以前のプロジェクトで悪い経験をしたかもしれません。彼らのメンテナンス担当者は不満を述べています：「このたわごとは文書化されていません！」。彼らが次のプロジェクトのための新しい要件を書いているとき、それは耳に鳴り響いています。
コードの文書化とメンテナンスギャングのコンテキストの提供に真剣に取り組んでいる場合、この要件は自動的に満たされます。だから、それについて猫にしないでください！
結局、21％でも29％でも、誰も気にしないでしょう。クライアントはあなたの内容を独立した開発者によってレビューされ、彼はあなたが何をしたかをよりよく理解するでしょう。
現在、このプロジェクトに取り組んでいない人々がどのように存在するかを理解していない多くのプログラマーに会いました。
彼らが知っているすべてのものについて、IS誰もが知っています。
誰かが現在知っていることのすべてを知らない場合、それらの人々は彼らに対して「ばか」です。
この標準を使用すると、人々にコメントを書く習慣を強いることができます。
彼らは99％の時点で役に立たないコメントを書くかもしれませんが、「EVERYONE KNOWS」というものの1つを実際に書き留めることがあるかもしれません。しかし、別の理由で元に戻されました）コードのその時点でのコメントで明らかでした。
明らかでないバグのある行にコメントがあると、将来のプログラマーが誤ってプログラムを完全に破壊するのを防ぐのにも役立ちます（特に、「テスト中」の部分がクイックテストの実行時に明らかでない場合）。