場合によっては、大きなコード ブロックを説明する「メジャー」コメントを書き、そのコード ブロック内のいくつかの行を説明する「マイナー」コメントを書きたいことがあります。
// Major comment
// Minor comment
...
// Minor comment 2
...
主要なコメントは、そのすぐ下にコードがないと奇妙に見えます。また、下に記述されているコードの量を視覚的に判断することもできません。
これらのコメントをどのようにスタイルしますか?
(少し前に Code Complete でこれについて読んだことを覚えていますが、私はその本を所有していません。)
「主要な」コメントには複数行のコメントを使用します。
/*
* yada yada yada
*/
また、マイナーなものには 1 行のコメントを使用します。
/* */ スタイルのコメントを使用することを好まない人がいることは知っています。ブロックを自動的にコメントしたり、コメントを解除したりするのが難しくなるためです ... しかし、私はそれらの見た目が好きで、コードは見た目が美しくあるべきだと強く信じています。読んだ。
これはまた、詳細を読まなくてもコードの構造の大部分を解析できるはずであることを意味します。つまり、私はかなり多くの空白と区切りコメント行を使用して物事を分割する傾向があることを意味します。したがって、コメントしたいブロックについては、次のように書くかもしれません。
/**
* detailed description ...
*/
code
// -- minor comment
code
code
// --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
// 主なコメント // ------------- ... // マイナーコメント ... ... // マイナー コメント (行末)
次のコードブロックの「見出し」またはセパレーターのように見せるために、次のようなものを使用します。
// ***** Major comment *****
// Minor comment
...
// Minor comment 2
...
もちろん、それは「主要なコメント」がほんの数語であることを前提としています
コード (ブロック) の上に主要なコメントを置き、前に空白行を置き、場合によってはすべて大文字にします。コードの邪魔にならないように、81 列目までインデントして右側に小さなコメントを置きました。どちらも // を使用しています。
アルゴリズムの「談話」については、次のように /* */ を使用します。
/*
* This is a long discourse on the code which follows it, usually
* placed at the beginning of a method and containing information
* which is not appropriate for the doc comments.
*/
「メジャー」コメントと「マイナー」コメントの違いは、それらが添付されているプログラム構造にあると思います。たとえば、メソッド レベルまたはクラス レベルのドキュメント コメントを「メジャー」と見なし、ブロック レベルまたは行レベルのコメントを「マイナー」と見なします。
/**
* This is major comment describing the method
*/
public void foo() {
if (...) {
// minor comment describing block
...
doSomething(); // minor comment describing line
}
}
コードをコメントで切り刻むのではなく、わかりやすい名前とドキュメント コメントを使用して、機能ユニットを独自のメソッドにリファクタリングすることをお勧めします。
ここでは、これはすべてかなりC中心です。C/C++ で書く傾向がある
/* file -- what it is -*-emacs magic-*- */
最初の行として。
/*
* Block comments like this
*/
if( I need a comment on a code block) {
/* I tend to write them like this */
x = x + 1 ; /* ... and write my */
/* line comments so */
}
私は通常// comments、内部コード用に予約し、古き良き BSD コメントをブロック コメントに残します。
Lispで
;;;; Four semicolons for "file-scope" comments
;;; Three for block comments over a large chunk of code
(defun quux (foo bar)
"Don't forget your docstrings, folks"
;; but big code comments get two semicolons
(let ((a 1)
(b 2)) ; and only one semicolon
(+ a b))) ; means an in-line comment.
# comment languages like Python and Ruby
# Have to live with one style of comment.
def quux(a,b):
return a + b # poor neglected things.
/* */私は通常、各セクションの先頭でを使用して、コード ブロックにコメントを付けます。コメントが「隠されている」と感じ、コードが後で拡張される可能性があり、コメントをマイクロマネージする必要があるため、特別な状況 (たとえば、トリッキーなコード) 以外ではインライン コメントを使用しません。例えば：
int parseEverything()
{
/* Initialize the parser. */
random_code_here();
still_more_init();
/// (Note: the above line still falls under the init section, even if it's separated by a newline.)
/* Main parser loop. */
while(!done_parsing) {
/* Grab the token. */
if(x) {
/* Preprocessor stuff. */
y();
} else {
/* Normal token. */
z();
}
/* Insert into tree. */
make_tree_node();
insert_into_tree();
/* Move to next token. */
++streamPtr;
/// (Note: the above could be expanded to take up multiple lines, thus
/// if an inline comment were used it'd have to be moved, if
/// you even remember there's a comment there.)
}
clean_up();
}
もちろん、コードが明らかな場合は、のようにコメントは必要ありclean_up()ません。ただし、コメントを含めてもそれほど問題はありません。後で展開すると、追加のクリーンアップ コードをどこに置くべきかを簡単に知ることができます。
このスキームを使用すると、コメントだけで簡単に関数をたどることができます。 parseEverythingには、初期化、メイン ループ、およびクリーンアップの 3 つの主要なセクションがあります。メイン ループ内で、トークン (プリプロセッサまたは通常) を取得し、それをツリーに挿入して、次のトークンに進みます。
ほとんどの場合、各セクションは独自の [セット] 関数を呼び出すため、セクションが大きくなった場合はリファクタリングが必要になることは明らかです。
複数行のコメントをそのようにフォーマットすることを追加する必要があります（私の「IDE」（ ）は、デフォルトのスクリプト（私のディストリビューション用）を使用してすべての行にVim挿入します。これは便利です）：*
/*
* This is a comment which normally would be on one line, but is either split into multiple
* lines for emphasis or so we don't have 160-character hard-to-read comments everywhere.
*/
また、私は と をコメント#elseし#endifます:
#ifndef FOO_H
#define FOO_H
#ifdef DEBUG
#else /* DEBUG */
#endif /* !DEBUG */
#endif /* FOO_H */
しかし、それは少し話題から外れています。
(ガードは( ) を前に付ける#include必要はありません。なぜなら、それらの使用は明らかであり、それは伝統だからです。=])not!
主なコメント
/*** Function - fooBar() ****************************
** Description **
** does the flooble using the bardingle algorithm **
** with the flinagle modification **
** Pre-condition **
** all moths are unballed **
** Post-condition **
** all moths are balled **
******************************************************/
void fooBar( int foo ) {
...
...
}
/*** Function - fooBar() END ***********************/
軽微なコメント
// note cast to int to ensure integer maths result
int i = (int)y / (int)x;
// Top-level (major) comment
theThing=doSomething();
// - Second-level (minor) comment
anotherThing=doSomethingWith(theThing);
// - - Third-level (minor-minor?) comment
yetAnotherThing=doSomethingWith(anotherThing);
// - Back to second level
destroy(anotherThing);
// Back to first level
helloWorld();もちろん、構文で許可されていない場合、識別トリックは適用されません (読み取り: Python)。
これは私のコメント スタイルの設定です。
/**
* This is a comment explaining
* what this method is actually doing
*/
public void foo()
{
// this is a simple comment
doSomething();
// this is a special comment
// explaining thoroughly what I'm doing
// using as many words as possible
// to be the most concise
doSomethingSpecial();
}
私はおそらくこのようにします：
// Here we do it
//
// So, be aware this text is just to make a silly
// long comment to show how it would look like
// in real code.
doTheRealThing();
// and this is another thingy
doOtherThing();
コメントが他のコードブロックの間に現れるコードを文書化しており、コメントがどこを参照しているかを本当に明確にしたい場合、時々私はその周りにブロックを書いているのを見つけます
// prepare for party
doIt();
// Here we do it
//
{
// So, be aware this text is just to make a silly
// long comment to show how it would look like
// in real code.
doTheRealThing();
// and this is another thingy
doOtherThing();
}
// another code that is not really affected by the comment
// above
die();
ブロックは、タスクを実行するために独自のローカル変数のセットを必要とする場合があり、ブロックはそれらのスコープを必要な場所に縮小する役割も果たします。おそらく、そのようなコードはそれぞれの関数に入れる必要がありますが、そうするとコードの品質が低下することがあります。さて、コメントメソッドについては、通常、ヘッダーファイルでコメントするだけで、次のようにします。
/**
* This function will return the current object.
*
* And now it follows the normal long stuff that's again
* a bit stretched to fill space...
*/
Object getCurrentObject();
コードの範囲のコメントを解除する場合、これらのコメントはコードを文書化するためだけに予約しているため、明示的に使用しません。使うよ
#if 0
Code in Here that's disabled
#endif
また、有効な C++ コードではないものをいくつか持つことからも解放されます (これらの区切り文字の間にあるものには、有効なトークンが含まれている必要があります)。ただし、問題がC＃でどのようになっているのかわかりません。
// A plate is displayed if a WorkFlowStepUpdate message is received
// whose:
// * Change_Type is License_No
// * Event_Type is GA, NA, or NG
// * New_Value is non-null and non-blank
// * Inspection_DateTime<(NOW-TimeInMinutesBeforeExpiringDisplaySignMessage)
//
// A plate is removed:
// * if it has been displayed for TimeInMinutesBefore...
// * a GA, NA, or NG CloseEvent is received whose New_Value matches
// a displayed plate
//
// If a plate is to be added to a full screen, the oldest plate on the display
// is removed to make room for the new plate.
.
.
.
.
.
// Record the ping status of each IP device
foreach (string s in th.Keys)
{
// We don't know if this is a wks or svr.
// But we can rely on 0 being bad, and we'll
// get the 'proper' state enumeration down in GetsOHInfo
//
if (IsItLive(s)) IPStates[s] = 1;
else IPStates[s] = 0;
IPTimes[s] = System.DateTime.Now.ToUniversalTime();
}