問題タブ [comment-conventions]

特定のデータを格納するためにHTMLコメントを使用する必要がありますが、 Dreamweaver <!-- #BeginLibraryItem "/File.lbi" -->やFrontpageなどのプログラムによって生成された既存のコメントスキームは使用したくありません。

どのコメントスキームが最も問題が少ないか、または少なくとも他の既存のコメント規則のように見えないかをどうやって知ることができますか？

PS：コメントの二重ハイフン「-」はレンダリングを壊すことがあると言われています。

コメントするときに別のメソッドを参照する必要がある場合があります。ここにPHPのいくつかの例があります：

barでは、クラスに非静的メソッドがあるとしたらどうでしょうBか。コメントで他のメソッドに名前を付ける最良の方法は何ですか？

編集

PHPのマニュアルmysqli->affected_rowsも同様に使用しているようPDO::beginTransactionです。ただし、メソッド名の後に括弧を含めることはできません。ここでの賛否両論は何ですか？メソッドの後に括弧が続くことは非常に明白です。それでは、なぜそれらを省略しないのですか？

事前にThx！

私は、自己文書化と実装の優雅さの完璧な禅のようなバランスを打ち出す、適度に短いが適度に複雑なコードのセグメント (オブジェクト、関数、クラス、特定の変数名のセットなど) の例を探しています。

それはあなたが本当に誇りに思っていることかもしれませんし、あなたが出会って「ああ！」を経験したことかもしれません。悟りの瞬間。

いくつかの潜在的な基準 (1 つの例ですべてを満たす必要はありません):

• まばらで集中
• 自明。おそらく非常に明確に書かれているので、プログラマーでなくても、構文や実装の詳細を理解していなくても、あなたがやろうとしていることを理解できるでしょう.
• 明白に有用 (ソートアルゴリズム、便利な再帰メソッドなど、複数のユースケースがあります)
• 頭がいい
• 啓蒙
• 製品の品質と機能 (例: 疑似コードではない)

コードの特別な点についての簡単な解説が続くサンプル スニペットを探しています。もちろん、最良の例は十分に文書化されているため、追加のコメントは最小限で済みます。

モデレーターへの注意: 私は stackoverflow を初めて使用するので、この質問が何らかの形で適切でないか、クローズする必要がある場合は、stackoverflow の規範に違反している箇所について説明を提供していただけますか? 私は人々の時間を無駄にするつもりはありません。

この質問の目標は、コミュニティによって提供および評価された例を通じて、適切なコメントの実践を学ぶことです。

コメントを書くとき、次のようなコメントを書くときに、タイプ (クラス、構造体など) について複数形で話す必要があることに気付くことがあります。

問題は、型名が単数形 (つまりThing) であるのに、コメントで複数形で話したいということです。

と言うとThings、 という型について話していることを読者に示唆しますThingsが、そうではありません。と言うとThing's、文法的に正しくないのでぎこちなく見えます (複数形ではなく、所有格または "Thing is" のいずれかです)。私は問題について話し、こう言うことができましたa list of Thing items

型の複数形を書く際に固執する良い規則は何ですか?

まず、この質問を認識しています: コード内のコメントの標準フォーマットはありますか?

しかし、それは私の答えではありませんでした。コードを書くときは常に、コメントがすべて一貫していることを確認する習慣を身に付けようとしますが、コード形式の規則については、ときどき優柔不断になります。特に、コードを 80 行程度にしたいので。

言うまでもなく、コード形式の規則は次のようにする必要があります。

• 読みやすい
• 変更が容易

また、コードのさまざまな部分でさまざまなコメント形式が存在する可能性があるため、一貫性と読みやすさを維持することが重要です。

ここではいくつかの例を示します。

単線

複線

テーブルの変更を行ういくつかの python スクリプトを実行するバッチ ファイルがあります。

1. 実行したくない 1 ～ 2 個の Python スクリプトをバッチ ファイルから削除するのではなく、ユーザーにコメント アウトしてもらいたい (そうすれば、次のユーザーはこれらのスクリプトがオプションとして存在することを知ることができます!)

2. また、コメントを追加して、バッチ ファイルを実行する前に、バッチ ファイルで更新する必要がある変数に特に注意を喚起したいと考えています。使えることがわかりましたREM。しかし、それは、ユーザーが実行した後に進行状況をユーザーに更新するためのもののようです。

コメントをより適切に追加するための構文はありますか?

.sqlファイルをどのようにコメント/文書化しますか？javadocなどと同様の規則はありますか？大規模なデータベースで一般的に行われていること-Facebook、Twitter、Googleなどの重いアプリケーション。