クライアントは現在のプロジェクトのコメントの25％を望んでいますが、どのように対応しますか？[閉まっている]

ジュニア開発者はこちら。

私は現在、私の会社の大顧客向けのWebアプリケーションで単独で作業しています。先月始めました。クライアントは、各ソフトウェアプロジェクトに少なくとも25％のコメントを求めています。

私は以前のアプリケーションのコードをチェックしました、そして私の観察はここにあります：

• 各ファイルはコメントブロックで始まります（パッケージ、最終更新日、会社名、著作権）

• すべての変数は名前でコメント化されます // nameOfCustomer public String nameOfCustomer

• すべてのゲッターとセッターがコメントされます

• 非常に少数の有用なコメント

開発者は、品質や有用性に関係なく、25％のしきい値に達するためにできるだけ多くのコメントを配置するようです。私の会社は、「クライアントが望んでいるとおりにそれを行う」と言っています。

私はこれについてクライアントと直接話しませんでした。これまでの私の議論は次のとおりです。

• 読み書きする無駄な行（時間の無駄）
• コメントが時々更新されない（混乱の原因）
• 開発者が実際に役立つコメントを使用または信頼する可能性が低い

このテーマに関するアドバイスは何ですか？状況をどのように処理すればよいですか？

ここにある他のすべての回答とコメントは、最初の反応に非常に反し、同僚で目撃した態度に反するため、本当に私をループに投げました。そこで、異議を唱えるためだけに、別のアプローチを説明したいと思います。

この答えの指針となる原則は、「顧客を喜ばせる」ことです。顧客を喜ばせることは、単に期待に応えることを意味するだけではありません。それは彼らの要求を非常に深く理解し、彼らが言うことを彼らが意味する方法で解釈することができ、彼らが求めるものを超えて提供することを意味します。他の答えは、代わりに悪意のあるコンプライアンスの原則によって導かれているようです。また、リピーターを獲得するには悪い方法であるため、疑わしいビジネス慣行もあります。

私にとって、クライアントが「25％のコメントが欲しい」と言うのを聞くと、それがダイアログの始まりです。私にとっては、他の答えとして「特定の構文カテゴリにランダム性を追加してください」ではなく、「このコードベースの初心者がすぐに起動して実行できるように、多くの説明テキストが欲しい」という意味です取っているようです。そして、私はその要求を真剣に受け止め、多くの説明的で有用なコメントを書き、新人をコードの構造に導き、意外なエンジニアリングの決定を指摘し、それらに入った理由を概説し、高レベルの英語を与えるつもりです複雑なコードセクションの説明（驚きがない場合でも）。この意図と理解が出発点です議論の-それは私たちが話し始める前です。私にとって、リクエストの意味は非常に明確であるため、その説明さえ必要ありません。しかし、もしあなたにそれがはっきりしないなら、もちろん彼らと一緒にチェックインすべきです！

さて、それが出発点である場合、ダイアログはどこに行きますか？ダイアログの次の部分は次のようになります。

1. これは、おそらくプロジェクトの第2フェーズで、彼らが作業に関心のあるツールの生産を超えた、さらに深刻な追加の努力になると期待しています。このプロセスとそれが追加の作業である理由を議論するのに数分かかるかもしれませんが、プロのプログラマーとして、良いコメントをすることがどれほど難しいか知っていると思うので、ここでは省略します。
2. 「深刻な追加の努力」とは、より長い時間予算とより大きな金銭的予算が必要になることを意味します。または、機能の予算を削減する必要がある場合があります。またはコメントの質と量について妥協する必要があるかもしれません。この部分は少し交渉になります。しかし、私の意見では、この余分な作業を行うためのコストについて非常に前もってすべきであり、これらのコストを引き受けてくれるクライアントにとって非常に重要な機能であることを確認してください。そして、それらがあれば-素晴らしい！余分な時間とお金が得られ、質の高いコメントが得られます。みんなが勝ちます。そして、コメント機能が彼らにとってあまり重要ではないことが判明した場合、ウィジェットをゆがめる能力を失うことを喜んでいるか、20x6のGranuaryの後半に締め切りを進んで喜んでいる場合、誰もが勝ちます：彼らは製品を手に入れます高品質のコメントを作成するために余分な労力を費やす必要はありません。

私は、ダイアログをすべきだと思うのはここではない行きます。

3. 低品質のコメントでクライアントを脅さないでください。彼らはあなたが彼らが費やしたい努力のレベルを選択するのを助けて、彼らが支払うことをいとわないようにしてください。25％のコメントを約束せずに、プロジェクトのビルド後にランダム性を自動生成してこの約束を果たすつもりであることを伝えます。
4. 計画を隠さないでください。25％のコメントを約束しないでください。それから、あなたがやろうとしていることを伝えずにランダム性を自動生成します。とき、彼らは（ない場合）に気づく、あなたの両方が大きな時間を失う：彼らは、彼らが得た製品に不満がある、とあなたは負の単語の口を取得します。
5. 彼らがコメントを望まないことを彼らに納得させようとしないでください。彼らは明らかにコメントを求めています。さまざまなアプローチのトレードオフについて議論します：はい！コードベースの新規参入者をフレンドリーにする別の方法について議論してください：はい！彼らが何を望んでいるかわからないことを伝えてください。あなたは彼らと協力して彼らが望むものを手に入れたい。それが何であるかを理解し、彼らが承認した予算でそれを彼らに提供する最善の方法を見つけ、彼らが持っているリソースが不十分な場合、彼らが最も気にする機能を優先します。
6. コメントを書くのがどれほど難しいかについて言い訳をしないでください。コードを書くのは難しいです。コードのデバッグは難しい。コメントを書くのは難しいです。それが簡単だったら、彼らはあなたを雇っていないでしょう。苦情をスキップして、彼らが関心を持っているポイント、つまり、余分な労力が彼らにどのように影響するかについて、まっすぐになります。

顧客は王様です。したがって、請負業者として、クライアントが品質基準として定義したものは何でも満たす必要があります。または、外出するリスクがあります。

これは言われていることですが、（ここでは劣悪な）品質基準がどのように定義されているかは非常に重要です：

• 契約上の品質基準：提供されるコードは準拠する必要があります。そうでなければ、契約違反となります。選択の余地ない。

• 正式な企業品質基準：完全に機能していても、準拠していないコードは非常に多くの人々によって品質が悪いと見なされます。さらに悪いことには、よく知られているツールを使用して、このような品質指標を自動化および正当化することができます（ソナーキューブなど）。ほとんど選択肢はありません。

• クライアントの数人によって定義されたアドホック基準。ここでディスカッションを行うことができます。希望がある ：-）

この最後のケースでは、ある程度の柔軟性があり、外交的に要点を説明することができます。ここで、顧客の基準に反するいくつかの議論：

• 生産性の問題：コーディングは2回行われます（英語で1回、コードで1回）。
• 精度の問題：コードで変更が行われた場合、コメントで変更を行わなければ、コメントが役に立たなくなる可能性があります。
• リファクタリングの問題：リファクタリングツールがコメント内の変数名を処理しないため。
• リスクの問題：コメントの曖昧さ（または陳腐化）により、混乱が生じ、バグが増加するリスクがあります。
• 量は質ではない
• StackOverflowの役に立たないコメントのこの面白いコレクション。
• この記事では、高いコメント率がコード臭の兆候でさえあると主張しています。

しかし、悪いことに反対して顧客に立ち向かうのではなく、単により良いアプローチを促進することができます：

• きれいなコード（お客様に本を提案してください。コメントと自己文書化コード専用の説得力のあるセクションがあります）。
• ドキュメンテーションの実践：把握するのが最も難しいこと、したがって、たとえばクラス間の関係や相互作用などの最も価値のある情報は、別のドキュメント（たとえば、1000個のコメントワードではなくUML画像？）

それでも顧客が納得していない場合は、ツールを使用して、javadocまたはなどのコメント付きのドキュメントを自動的に生成する実験的な代替案を提案できますdoxygen。これにより、量（コードの25％）から品質（わかりやすいjavadocを生成）にフォーカスを移すことを提案します。

クライアントは、各ソフトウェアプロジェクトに少なくとも25％のコメントを求めています。

クライアントはコメントの25％を本当に必要としているのですか、それともクライアントはコードをできるだけ記述的にしたいのですか？

私見、クライアントは彼が望むものを知っているが、彼が必要とするものではない。クライアントは開発者ではなく、自身のワーカー/顧客からフィードバックを受け取るため、クライアントは氷山の最上部のみを見ることになります。

あなたのクライアントはいくらかの疑似知識を持ち、コードを適切に文書化し、簡単で安価に保守できることを望んでいます。このためのツールはコメントです（彼の心の中）。

彼と話してみて、自分自身を説明する適切に記述されたコードとコメント付きの別の悪い記述のあるコードスニペットを用意してください。ほんの数行です。必要に応じてこれを示し、言葉の絵として使用します。

クライアント/スーパーバイザー/何でも話して、最新のバージョン管理の原則（ファイルの先頭にコメントは不要）ときれいなコード（この本もお勧めします）を教えてください。

たぶん、あなたがそれを十分に示し、コメントだけでなくクリーンなコードを望んでいることをクライアントに理解させることができれば、あなたとあなたのチームはより良いコードを書いて（コメントははるかに少ない）、すぐにあなたが維持する価値のある良い開発者であることを示すことができます。

これは、文字通り「最小文字数制限に達するためのテキスト」が続く1行で構成される、おかしなStack Overflowの回答を思い起こさせます。

これが発生した場合、2つのグループの人々に障害があるという議論を行うことができます。

1. 制限を設けた人々—明らかにそれは過剰であり、人々が人工ノイズを追加せずに適切に形成された情報を提出することを防ぎます

2. 適切に形成されていない情報を提出した人々は、システムが実際の物質を追加するように促したときに人工ノイズを追加しました

時には、質問はシンプルで話題の両方になることがあり、数語以上の発言はありません。ただし、これは非常にまれです。ほとんどすべての場合、言うべき内容がたくさんあります。他に何もなければ、キャラクターの制限を回避する方法は、ランダムなノイズを投稿にダンプすることではないことは、目もくらむほど明白なはずです。

あなたが直面しているこのコメントの状況はほとんど同じです。開発者はコメントをリクエストし、ランダムノイズをコードにダンプすることでコメントを実装しました。変数の宣言のすぐ隣にある変数の名前を文書化することは破壊行為です。それは決して起こらなかったはずです。

「しかし、どうすれば25％に到達できるでしょうか？」実体の実際のコメントを書くことによって。より多くの単語、より良い単語、最高の単語を使用して、機能の効果を文書化します。説明を展開します。エッジケースの詳細を説明します。

ただし、元のポイントに戻ると、「ソースコードの25％」は非常にarbitrary意的であるため、クライアントもここで部分的に障害が発生しています。ただし、最終的にはクライアントであるため、最大限に活用してください。しかし、私は「最高」を意味します。これまで起こってきた「最悪」ではありません。

この要件で何が大騒ぎなのかわかりません。

コードの基本的な酸素化によって、おそらくすでに10％程度になっています。そして、自分のために書いたコメントの5％をさらに取りましょう（沈黙の誓いを立てていなければ、5％は控えめな見積もりの​​ようです）。この時点では、約15％です（はい、はい、90％の5％は5％未満です、ピッキングしないでください）。doxygenが10％未満の場合、メソッドが非常に長い可能性があります。通常、それらをより小さな（主にプライベート/保護された）ものに分割するか、より汎用的なヘルパークラスなどを使用することをお勧めします。

次に、コメントテキストの残りの部分で、設計上の考慮事項と使用シナリオをクラス/ファイルレベルのコメントに入れます。いくつかのテーブルまたはASCIIアート（またはレンダリング時に見栄えの良いものを生成するdoxygenコード）を用意します。もちろん、あなたのプロジェクトが何であるかはわかりませんが、ダミーのコメント（酸素化ボイラープレート以外）なしでこれを行うことができ、25％に近いものに到達できると思います。

たとえば、25％ではなく20％だけである場合、クライアントはその数を任意の値として指定しただけで、それで問題ないはずです。とにかく、コメントに何を含めるべきかを議論するために彼らと話をしてください。彼らに満足しているかどうかを確認するために、コメントファイルの例を示します。彼らがそうであれば、それはそれです、彼らは何かが欠けていると思うならば、彼らは何が欠けているかを教えてくれます。彼らはあなたに「私たちは考えられる余分なコメントを提案することはできませんが、私たちはあなたにいくつかを追加してほしい」とは言いません。

PS-標準Javaコンテナのコー​​ドを見て、どのように到達できるかを確認してください。

コードに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

等。

五。愚かなルールを最大限に活用してください。有用で意味のあるコメントを書くようにしてください。ねえ、それは良い運動かもしれません。

ああ、ところで、あなたはいつでもメトリックをゲームにかけることができると付け加えてもいいでしょうか。

ある雇用主が、私たちが1週間に何行のコードを生成したかによって、プログラマの生産性を測定し始めると言ったことを思い出します。私たちが会議でこれを言われたとき、私は言った、素晴らしい！簡単にスコアを上げることができます。もう書く必要はありません

x=x+4;

代わりに次のように書きます：

x=x+1;
x=x+1;
x=x+1;
x=x+1;

ループ？忘れて、コードを10回コピーして貼り付けます。等。

したがって、ここで、コメントの行を数える場合は、各行を短くして次の行でアイデアを続けます。コメントの内容に変更がある場合は、既存のコメントを更新しないでください。日付を入力し、テキスト全体をコピーして、「更新日」と新しい日付を書きます。クライアントが質問した場合、履歴を維持する必要があると彼らに伝えます。などなど

任意のメトリクスは、あまりにも多くのプロジェクトでの現実のようです...

これは、コンプライアンスを確保するために関数が不必要に分割されるため、または任意のSLoCの長さを超えるためにファイルが分割されるため、最大サイクロマティック複雑性などのダム要件でよく見られます。

コメントはコードに追加し、何が起こっているかを説明する必要があります（コードを繰り返すだけではありません！）。

つまり、これが顧客の望みであり、会社が提供することに同意した場合、QAマネージャーが常識を身に付けない限り、行き詰まってしまいます。

短期的には、あなたが本当にできることは何もありません。それと一緒に行きます。

また、コード内の受動的で積極的な抗議と馬鹿げた冗談について、このスレッドで私が見ているすべての愚かなアイデアを無視する必要があります。

クライアントとの信頼関係を確立したら、彼らはあなたの推論に耳を傾けることができます-これはかつて影響力を持っていた1人からの愚かな要求であり、社内ではほとんどサポートされていないことがわかります。

いかなる状況下でも、クライアントの許可なしに反対すべきではありません。

ここにいる仲間のプログラマーの想像力の欠如に失望しています。

私には、クライアントがいくつかの調査を行ったようです。品質コードには通常、コメントの約25％が含まれていることをどこかで読んだことがあります。明らかに、彼は将来のメンテナンスについて心配/心配しています。さて、彼はどのように契約に結び付けられることになる要件文書でそれを具体的にするのでしょうか？それは簡単ではありません。それも不可能かもしれません。それでも、彼は自分のお金の価値を確実に得られるようにしたいので、いくつかの品質指標を列挙します。

それは私にはまったく愚かまたはばかげて聞こえません。要件を書いた人は、おそらくプログラマーではありません。彼らは以前のプロジェクトで悪い経験をしたかもしれません。彼らのメンテナンス担当者は「このたわごとのどれも文書化されていません！」と不平を言っています。彼らが次のプロジェクトの新しい要件を書いているので、耳を澄ませています。

コードを文書化し、メンテナンスギャングにコンテキストを提供することに真剣であれば、この要件は自動的に満たされます。だから、それについて猫にならないでください！

最終的には、21％であろうと29％であろうと、誰も気にしません。クライアントは、独立したデベロッパーがあなたのものをレビューし、彼があなたが何をしたかをよりよく理解するでしょう。

私は、現在このプロジェクトに取り組んでいない人々の存在を理解していない多くのプログラマーに会いました。

彼らにとって、彼らが知っていることはすべて、誰もが知っています。

誰かが現在知っているすべてを知らない場合、それらの人々は彼らにとって「バカ」です。

この標準を使用すると、人々にコメントを書く習慣を強要することができます。

99％の時間、役に立たないコメントを書くこともありますが、実際には「誰もが知っている」ことの1つを書き留めることもあります。また、チームの新しい人は、しかし、その後、別の理由で元に戻されました）、コードのその時点でコメントがあれば明らかでした。

明白でないバグのある行にコメントを付けることは、将来のプログラマが偶然にプログラムを完全に壊すのを避けるのに役立ちます（特に、「壊れている」部分がクイックテストを行うときに明らかでない場合）。