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

閉じた。この質問は意見に基づいています。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集して事実と引用で答えられるように質問を更新してください。 4年前に閉鎖されました。 バージョン管理のコメントについて、他のユーザーは何をしますか/推奨します-過去形または現在形？ すなわち xをyに変更しました。 または xをyに変更します。

12 comments  source-code 

私はかなり大きなプライベートコードベースを持っていますが、これは約10年にわたって進化しています。私はphpDocumentorを使用していませんが、オープンブロックプロジェクトではdocblockセクションを使用することが標準になっているため、リポジトリ内のすべてのパブリックメソッドにもdocblockを記述することを採用しました。ほとんどのブロックには、すべてのパラメーターと戻り値の型に関する小さな説明と型ヒントが含まれています。 静的解析の登場により、これらのタイプヒントは矛盾やバグの発見に大いに役立ちました。最近、PHPのtypehintsを使用して、可能な場合はすべてのパラメーターと戻り値の型ヒントを含むように、コードベース全体（PHP7.2で実行中）を変換しました。そして今、私は疑問に思っています...これらのdocblock typehintsは冗長ではありませんか？すべてのdocblockを絶えず変化するコードと同期させ、新しい情報を追加しないため、それらを完全に削除する方が良いのではないかと思っています。 一方で、ドキュメントを削除することは、それが冗長であっても気分が悪くなります。もう1つは、既にタイプヒントが付けられている日常的なタイプヒントの繰り返し禁止の原則を破りたいという気持ちです。

12 php  comments 

私は「スパゲッティコード」プロジェクトに取り組んでおり、バグを修正して新しい機能を実装している間、コードをユニットテスト可能にするためにリファクタリングも行っています。 コードはしばしば非常に密結合または複雑であるため、小さなバグを修正すると多くのクラスが書き直されます。そこで、リファクタリングを停止するコードのどこかに線を引くことにしました。これを明確にするために、次のような状況を説明するコメントをコードにいくつか落とします。 class RefactoredClass { private SingletonClass xyz; // I know SingletonClass is a Singleton, so I would not need to pass it here. // However, I would like to get rid of it in the future, so it is passed as a // parameter here to make this change …

11 refactoring  comments 

正規表現にコメントするための一般的な慣行はありますか：正規表現の別の部分を参照するインラインコメントまたはすべての表現に対する一般的なコメントですか？

11 documentation  coding-style  comments 

今日は同僚と話していました。2つの異なるプロジェクトのコードに取り組んでいます。私の場合、自分のコードに取り組んでいるのは私だけです。彼女の場合、複数の人が同じコードベースで作業します。これには、かなり定期的に（8〜12か月ごとに）出入りする生協学生も含まれます。彼女は自分のコメントに寛大であり、あちこちにそれらを置いていると言った。彼女の推論は、コードの大部分が彼女によって書かれておらず、彼女以外の誰かによって変更される可能性があるため、物事がどこにあり、何をしているのかを思い出すのに役立つということです。その間、私はコード内のコメントを最小限に抑え、明白でない回避策またはバグがある場所にのみコメントを配置しようとします。ただし、コード全体をよりよく理解し、コードをより直接制御できます。 そのコメントでの私の意見は最小限であり、コードはストーリーの大部分を伝えるべきですが、彼女の推論も理にかなっています。彼女の推論に欠陥はありますか？コードが乱雑になる場合がありますが、短期から中期に多くの人が作業している場合、最終的には非常に役立ちます。

11 coding-style  team  comments 

Javaで非推奨のクラスを識別するためのコメントを追加する最良の方法を知りたいです。クラスの先頭に追加された以前のコメントを削除して、別のプログラマーがそのクラスの目的を理解できるようにするか、コメントの下に追加する必要がありますか？

11 java  code-quality  api  comments 

自分用に小さなスクリプトを作成しているときは、コードをコメントでスタックします（コードよりもコメントが多い場合があります）。私が話している人の多くは、これらのスクリプトは個人的なものであっても、文書化する必要があると言っています。しかし、コメントはドキュメントの形式ではありませんか？ これではないでしょう： $foo = "bar"; # this is a comment print $foo; # this prints "bar" 特に開発者が私のコードを使用している場合、ドキュメントと見なされますか？または、ドキュメントはコード自体の外にあると見なされますか？

11 documentation  comments 

私はかつて、ドキュメントにXMLコメントを要求するファンでした。それ以来、私は2つの主な理由で考えを変えました。 優れたコードのように、メソッドは自明でなければなりません。 実際には、ほとんどのXMLコメントは無意味なノイズであり、付加価値はありません。 多くの場合、GhostDocを使用して一般的なコメントを生成しますが、これは役に立たないノイズとは次のことを意味します。 /// <summary> /// Gets or sets the unit of measure. /// </summary> /// <value> /// The unit of measure. /// </value> public string UnitOfMeasure { get; set; } 私には、それは明白です。とはいえ、含める特別な指示がある場合は、XMLコメントを絶対に使用する必要があります。 私はこの記事からのこの抜粋が好きです： 時々、あなたはコメントを書く必要があるでしょう。しかし、それは規則ではなく例外であるべきです。コメントは、コードでは表現できないものを表現している場合にのみ使用してください。エレガントなコードを記述したい場合は、コメントを削除し、代わりに自己文書化コードを記述してください。 コードがそれ自体で説明するのに十分でない場合にのみXMLコメントを使用すべきだと思うのは間違っていますか？ これは、XMLコメントによってかなりのコードが見苦しく見える好例です。それはこのようなクラスを取ります... public class RawMaterialLabel : EntityBase { public long Id { get; set; } …

10 .net  programming-practices  development-process  documentation  comments 

私は適切に文書化されたコードの支持者であり、そのコードの考えられる欠点をよく知っています。それはこの質問の範囲外です。 Visual StudioのIntelliSenseがどれだけ好きかを考慮して、すべてのパブリックメンバーにXMLコメントを追加するというルールに従うのが好きです。 ただし、冗長性には1つの形式があり、私のような過度のコメンターでさえも気になります。例として、List.Exists（）を取ります。 /// <summary> /// Determines whether the List<T> contains elements /// that match the conditions defined by the specified predicate. /// </summary> /// <returns> /// true if the List<T> contains one or more elements that match the /// conditions defined by the specified predicate; otherwise, false. /// …

10 documentation  comments  intellisense 

equals、compareToなどの広く知られたメソッドにコメントを書くことは良い習慣ですか？ 以下のコードを検討してください。 /** * This method compares the equality of the current object with the object of same type */ @Override public boolean equals(Object obj) { //code for equals } 私の会社は、上記のようなコメントを入力することに激怒しています。上記のJavadocコメントは必要ですか？equalsメソッドなど（compare、compareTo）などが何をするのかが明確でよく理解されていませんか？ あなたの提案は何ですか？

10 java  comments 

「ヘッダーコメント」の形式はプログラマーによって異なることに気づきましたが、「良い」ヘッダーコメントの例は何でしょうか？

10 c++  coding-style  comments  code-formatting  headers 

私はRobert C. MartinのClean Codeを読んTILTでいますが、このフレーズは一部のコードサンプルに不可解に表示されています。例（ちなみにJavaです）： ... public String errorMessage() { switch (status) { case ErrorCode.OK: // TILT - Should not get here. return ""; case ErrorCode.UNEXPECTED_ARGUMENT: return "Unexpected argument"; case ErrorCode.MISSING_ARGUMENT: return "Missing argument"; ... } ... コンテキストから、TILT到達できない状態であり、コンパイラを満たすためにのみ含まれている状態を指定していると思います（たとえば、上記のコードでは、状態がの場合はエラーメッセージが表示されないためTILT、ErrorCode.OKケースに表示されますOK）が、よく分かりません。 誰かがTILT/の意味が何であるか知っていますか？

9 java  clean-code  comments  conventions 

プロジェクトを離れようとしています。行く前に、上司からコードの文書化を求められました（あまり文書化していません）。大したことではなく、プロジェクトはそれほど複雑ではありません。しかし、私は自分のドキュメンテーションの中で、「XYZの行でそのようなことが起こることに気づく」と言いたい場所を見つけています。 この場合、コードの1行を追加または削除するとすぐにドキュメントが古くなるため、特定の行番号を参照しても意味がありません。行番号で参照せずに特定のコード行を参照するためのベストプラクティスはありますか？ 私は次のようなコメントでコードを散らかすことを検討しました： /* linetag 38FECD4F */ ここで、「38FECD4F」はその特定の行の一意のタグです。次に、「 '38FECD4F'とタグ付けされた行で、そのようなことが起こることに注意してください」というドキュメントを挿入できます。 他のアイデアは？コードユニットの特定の部分よりも全体としてドキュメント化する方が一般的には良いと思いますが、この特定のプロジェクトの場合、手続き型コードの長い列があり、小さいユニットにリファクタリングされたことはありません。

9 documentation  comments 

JavadocをDRYで記述したい。しかし、Javadocに関するOracleのドキュメントでは、オーバーロードメソッドのコメントに同じことを再度記述しています。繰り返しは避けられませんか？

9 documentation  comments  dry  javadocs 

現在のところ、この質問はQ＆A形式には適していません。回答は事実、参考文献、専門知識によって裏付けられると期待していますが、この質問は、議論、議論、投票、または拡張ディスカッションを求める可能性があります。この質問を改善でき、再開できると思われる場合は、ヘルプセンターにアクセスしてください。 7年前休業。 私も同じことをしています。コードに「やること」があるときは、と書き//TODO ...ます。しかし、これがいつ始まったのか、すべての大文字で「to-do」を書く理由があるのか​​どうか知りたいのですが。

9 comments