タグ付けされた質問 「comments」

C＃でのXMLコメントのベストプラクティスの推奨事項を探しています。プロパティを作成すると、予想されるXMLドキュメントは次の形式になっているようです。 /// <summary> /// Gets or sets the ID the uniquely identifies this <see cref="User" /> instance. /// </summary> public int ID { get; set; } しかし、プロパティのシグネチャはすでにクラスの外部クライアントが使用できる操作を示しているため（この場合は両方getとset）、コメントはおしゃべりすぎて、おそらく次のようになります。 /// <summary> /// ID that uniquely identifies this <see cref="User" /> instance. /// </summary> public int ID { get; set; } Microsoftは最初の形式を使用しているので、暗黙の慣習のようです。しかし、私が述べた理由のために、2番目の方が優れていると思います。 この質問は建設的ではないとマークされるのが得意であると理解していますが、コメントしなければならないプロパティの量は膨大であるため、この質問にはここにある権利があると思います。 …

19 c#  .net  programming-practices  comments 

jQueryコードのコメントから多くの問題番号を見ました。（実際、jQueryコードには69の問題番号がありました。）良い習慣になると思いますが、ガイドラインを見たことはありません。 それが良い方法である場合、この方法のガイドラインは何ですか？

18 comments  issue-tracking 

私が知っている限り、いくつかはそうですが、人気のあるものはどれもありません。コメントをネストすることについて何か悪いことはありますか？ 私が取り組んでいる（小さな）言語でブロックコメントをネストする予定ですが、これが悪い考えかどうかを知りたいです。

18 language-agnostic  syntax  comments 

閉じた。この質問は意見に基づいています。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集して事実と引用で答えられるように質問を更新してください。 4年前に閉鎖されました。 私はしばしばそのようなコメントが使用されるのを見ました： function foo() { ... } // foo while (...) { ... } // while if (...) { ... } // if そして時には if (condition) { ... } // if (condition) 私はこのプラクティスを理解したことがないため、適用しませんでした。コードが非常に長いため、このエンディング}が何であるかを知る必要がある場合は、おそらくコードを個別の機能に分割することを検討する必要があります。また、ほとんどの開発者ツールは、一致するブラケットにジャンプできます。最後に、最後の点は、私にとって、DRY原則への明らかな違反です。条件を変更する場合は、コメントも変更することを忘れないでください（そうしないと、メンテナーやあなたにとっても面倒になります）。 なぜ人々はこれを使用するのですか？それを使うべきですか、それとも悪い習慣ですか？

18 source-code  comments 

私のチームの開発者の1人は、メソッドの署名のEVERYパラメーターにjavadocコメントを書く必要があると考えています。私はこれが必要だとは思わないし、実際、それは有害でさえあると思う。 まず、パラメーター名は説明的で自己文書化されるべきだと思います。パラメータの目的がすぐに分からない場合は、おそらく間違っています。ただし、パラメータの目的が不明な場合があることは理解しています。そのため、その場合は、パラメータを説明するjavadocコメントを作成する必要があります。 しかし、すべてのパラメーターに対してこれを行う必要はないと思います。パラメータの目的がすでに明らかな場合、javadocコメントは冗長です。あなた自身のために余分な仕事を作成しているだけです。さらに、コードを保守する必要がある人のために余分な作業を作成しています。メソッドは時間とともに変化し、コメントを維持することはコードを維持することとほぼ同じくらい重要です。「XはYをZの理由で行う」などのコメントを何回見て、そのコメントが古いことを確認しましたが、実際にはメソッドはXパラメーターさえも取りません。人々はコメントを更新するのを忘れているので、それは常に起こります。誤解を招くコメントは、まったくコメントしないよりも有害であると主張します。したがって、過剰なコメントの危険性があります。不要なドキュメントを作成することにより、 しかし、私は自分のチームの他の開発者を尊重し、おそらく彼が正しいと私は間違っていることを受け入れます。だからこそ、仲間の開発者に質問を投げかけます。実際、すべてのパラメーターにjavadocコメントを書く必要がありますか？ここでは、コードは会社の内部にあり、外部の第三者によって消費されることはないと想定しています。

17 java  documentation  source-code  comments  maintainability 

私たちのショップの上級開発者は、コードが変更されるたびに、責任のあるプログラマーが自分が何をしたかを示すインラインコメントを追加する必要があると主張しています。これらのコメントは通常次のようになります// YYYY-MM-DD <User ID> Added this IF block per bug 1234. リビジョン管理にはTFSを使用しますが、この種のコメントは、インラインノイズよりもチェックインメモとしてはるかに適切であると思われます。TFSでは、チェックインを1つ以上のバグに関連付けることもできます。古い、よく変更されるクラスファイルの一部は、コメントとLOCの比率が1：1に近いように見えます。私の目には、これらのコメントによりコードの読み取りとゼロ値の追加が難しくなります。 これは他のショップでの標準的な（または少なくとも一般的な）慣行ですか？

17 coding-standards  comments 

かなりのコードベースでは、次のようなコメントを見ることができます。 // Workaround for defect 'xxx', (See bug 1434594 on Sun's bugparade) いくつか質問がありますが、それらはすべて関連しています。 プログラムのコメントにSO質問へのリンクを入れても大丈夫ですか？ // We're now mapping from the "sorted-on column" to original indices. // // There's apparently no easy way to do this in Java, so we're // re-inventing a wheel. // // (see why here, in SO …

16 comments 

NotImplementedExceptionあなたがまだ書いていないコードを投げることは悪い習慣と考えられていますか？おそらくTODOコメントはより安全だと考えられますか？

15 .net  comments  coding  exceptions 

ここで何が求められているかを伝えるのは難しいです。この質問は曖昧、曖昧、不完全、過度に広範、または修辞的であり、現在の形式では合理的に答えることができません。この質問を明確にして、再開できるようにするには、ヘルプセンターに アクセスしてください。 8年前に閉鎖されました。 好奇心から、コメントを許可しない言語は、自己コメントのコードを書くことを余儀なくされるので、より読みやすいコードを生成するかどうか疑問に思い始めました。 繰り返しますが、気にしないので、以前と同じように悪いコードを書くことができます。しかし、あなたの意見は何ですか？

15 comments 

現在のところ、この質問はQ＆A形式には適していません。回答は事実、参考文献、または専門知識によってサポートされると予想されますが、この質問は議論、議論、世論調査、または広範な議論を求める可能性があります。この質問を改善し、場合によっては再開できると思われる場合は、ヘルプセンターをご覧ください。 7年前に閉鎖されました。 どの言語でも典型的なif-else-constructを書いているときはいつでも、コメントを追加するための（読みやすさと概要の点で）最良の方法は何だろうと思います。特にelse節にコメントするとき、コメントはいつも私にとっては場違いな感じがします。次のようなコンストラクトがあるとします（例はPHPで記述されています）。 if ($big == true) { bigMagic(); } else { smallMagic() } 次のようにコメントできます。 // check, what kind of magic should happen if ($big == true) { // do some big magic stuff bigMagic(); } else { // small magic is enough smallMagic() } または // check, what kind …

15 comments 

競合マーカーを検討してください。すなわち： <<<<<<< branch blah blah this ======= blah blah that >>>>>>> HEAD この質問を投稿する動機となった特定のケースでは、担当のチームメンバーがアップストリームからブランチへのマージを完了したばかりで、場合によっては、これらをコメントとして、今までの内容に関する一種のドキュメントとして残していました解決しました。彼はそれをコンパイルされた状態のままにして、テストに合格したので、あなたが思うほど悪くはありません。 本能的には、私は本当にこれに異議を唱えましたが、悪魔が自分自身を擁護しているので、なぜ彼がそれをしたのかがわかります： マージの結果として変更されたものを他のチーム開発者に強調するためです。 特定のコードに精通している人は、コメントが示す懸念に対処できるため、推測する必要がありません。 アップストリームマージは適切な痛みであり、すべてを適切かつ完全に解決するための時間を正当化するのが難しい可能性があるため、いくつかの半完全なFIXME通知が必要です。 私の反対は本能的でしたが、それを合理的に正当化するか、自分の立場をより賢く見たいと思います。誰かが私にいくつかの例や、誰かがこれをやっていると悪い時間を過ごした経験や、それが悪い習慣である理由を教えてもらえますか（または悪魔の擁護者を演じてそれをサポートすることができます）。 私自身の当面の懸念は、関係するファイルの1つを編集し、変更を取得し、実際の競合を取得したが、コメントされたファイルも取得した場合、明らかに迷惑になることでした。そうすれば、本当に非常に面倒なファイルになっていたでしょう。幸いなことにそれは起こりませんでした。

14 version-control  comments  coding-style 

私は、計算幾何学やグラフィックス、およびこれらの種類のトピックに触れる多くの（主にc ++およびjavascript）コードを書くので、視覚図は問題を解決するプロセスの不可欠な部分であることがわかりました。 「ああ、手書きの図をなんらかの方法でコメントとしてコードの一部に添付できたら素晴らしいのではないか」と判断しました。これにより、私が取り組んだものに戻ることができます。数日、数週間、数か月前、そしてはるかに迅速にアルゴリズムを再作成します。 視覚的な学習者として、単純な図はあらゆるタイプの非自明なデータ構造に関する理解と推論に役立つため、これはほとんどすべてのタイプのプログラミングで生産性を向上させる可能性があると感じています。たとえばグラフ。大学でのグラフ理論の授業中、私は実際に図式表現を描くことができるグラフ関係を本当に理解することができただけでした。 そう... 私の知る限り、IDEを使用して写真をコードへのコメントとして保存することはできません。 私や他の誰かが、イメージをbase64バイナリ文字列に変換してコードに挿入できる、かなり使いやすいツールを考え出すことができると考えました。 変換/挿入プロセスを十分に合理化できれば、ダイアグラムと実際のコードの接続がはるかに良くなるため、ノートブックを時系列に検索する必要がなくなります。さらに素晴らしい：IDEのプラグインが自動的に画像を解析して表示します。理論的な観点から、これについて絶対に難しいことはありません。 私の推測では、お気に入りのIDEを拡張し、これらのプラグインを維持する方法を実際に把握するには、余分な時間がかかるので、同じ解析を行う一種のコードポストプロセッサに完全に満足し、画像をレンダリングして、コードをブラウザや何かの中に並べて表示します。私は貿易でjavascriptプログラマーだからです。 人々はどう思いますか？誰もこれにお金を払うでしょうか？私は...するだろう。しかし、私は、私またはかなりの数の同僚がそのようなものにお金を払うかどうかに関係なく、そのようなものが成功する可能性が高い唯一の方法は、オープンソースのリリースを通じてであることを指摘するでしょう。

14 productivity  code-reviews  comments  workflows  image-manipulation 

20年前のレガシーコードベースにリファクタリングを行っており、同僚とコードのコメント形式（plsql、java）について議論しています。 コメントにはデフォルトの形式はありませんが、ほとんどの場合、人々はコメントで次のようなことをします。 // date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment 私が望む将来および過去のコメントの提案された形式は次のとおりです。 // {yyyy-mm-dd}, unique_author_company_id, comment 私の同僚は、コメントだけが必要であり、過去および将来のすべてのコメントをこの形式に再フォーマットする必要があると言います。 // comment 私の議論： メンテナンス上の理由から、いつ、誰が変更を行ったかを知ることが重要です（この情報はSCMにあります）。 コードは生きており、そのために歴史があります。 変更日付がないと、SCMツールを開いて長いオブジェクト履歴を検索しないと、変更がいつ導入されたかを知ることができないためです。 著者は非常に重要であるため、著者の変更は著者の変更よりも信頼できる 敏ility性の理由、SCMツールを開いてナビゲートする必要はありません 人々は、最近作成または変更されたものよりも、誰かが15年前にしたことを変更することを恐れます。 等 私の同僚の議論： 歴史はSCMにあります 開発者は、コード内のコードの履歴を直接認識してはなりません。 パッケージの長さは15,000行になり、構造化されていないコメントはこれらのパッケージを理解しにくくします 最善のアプローチは何だと思いますか？または、この問題を解決するためのより良いアプローチがありますか？

13 java  c#  programming-practices  code-quality  comments 

エンティティ、ビジネスロジック、およびデータアクセスクラスの有益なクラスドキュメント形式を探しています。 ここから次の2つの形式が見つかりました フォーマット1 ///----------------------------------------------------------------- /// Namespace: <Class Namespace> /// Class: <Class Name> /// Description: <Description> /// Author: <Author> Date: <DateTime> /// Notes: <Notes> /// Revision History: /// Name: Date: Description: ///----------------------------------------------------------------- フォーマット2 // =============================== // AUTHOR : // CREATE DATE : // PURPOSE : // SPECIAL NOTES: // =============================== // …

13 c#  documentation  comments 

技術的に不要な追加のローカル変数を使用して、何が起こっているのかを説明するのは良いスタイルですか？ 例えば： bool easyUnderstandableIsTrue = (/* rather cryptic boolean expessions */); if(easyUnderstandableIsTrue) { // ... } 技術的なオーバーヘッドに関しては、コンパイラがこの追加の行を最適化することを期待しています。しかし、それは不必要なコードの肥大化と見なされますか？私の目には、古いコメントのリスクを減らします。

12 coding-style  comments