104コメント34KB

みんな関数コメントどうしてる？

■ このスレッドは過去ログ倉庫に格納されています

0001コメントなし

NGNG

関数の説明するコメントって、どんな形式にしてます？

ちなみに俺は、C++の場合こう書いてます。

/////////////////////////////////////////////////////////
// int Hoge(int i)
// 戻り値：
//　○○○
// 説明:
// △△△
/////////////////////////////////////////////////////////

これをテキストファイルに保存して、そのつどコピペしてます。
でも、これってめんどい・・・
効果的なコメントの書き方してる人教えて。

00022get ◆8LDBMQ/E

NGNG

2get

0003デフォルトの名無しさん

NGNG

嫌。

0004デフォルトの名無しさん

NGNG

なにも書かない。これ最強。

0005デフォルトの名無しさん

NGNG

嘘を書く。これ最強。

0006デフォルトの名無しさん

NGNG

JAVAだとjavadocがあるからそれに準拠するのが当り前になるね。
そういうドキュメント生成ツールは使ってないの？>>1

0007デフォルトの名無しさん

NGNG

.hに引数と簡単なコメント入れるぐらいかな？
場合にもよるけど・・・

0008デフォルトの名無しさん

NGNG

>>5
それは最凶。

0009コメントなし

NGNG

>>6
JAVAのプログラムは何度も書いた事があるけど、javadocは
使った事なし・・・

それ以前に、コメントを書くのが面倒なんで、なんとかならんか
と・・・
行が増えるたびに「//」を入力したりとか。
/* */を使うと、まとめてコメントアウトしたりするとき面倒だし・・

また、雛形をコピぺするのも面倒・・・
複数行なんでIMEに登録もできんし・・・

この単純作業を皆どうやってるんだろうと思った次第です。

0010デフォルトの名無しさん

NGNG

Emacsならcomment-region一発だな。

0011デフォルトの名無しさん

NGNG

>>1

http://www.shiojiri.ne.jp/~tukahara/boss.html

このソフトなんてどう？シェアウェアだけどね。

0012デフォルトの名無しさん

NGNG

>>6
C, C++ なら doxygen を使うと Javadoc っぽくコメント付けできる。

http://www.doxygen.org/

Graphvis と組み合わせて使うと、クラス図もなかなか行けてる。

0013デフォルトの名無しさん

NGNG

マクロ使え

0014デフォルトの名無しさん

NGNG

>>13
同意。
漏れもマクロで一発入力できるようにしてある。

0015デフォルトの名無しさん

NGNG

私はこんな感じ。
/*============================================================================
関数名
戻り値：
　……。
説明：
　……。
============================================================================*/

>>1と大差ないけど、コメントの行数が増えてもこちらの方が
楽だと思う。

あとどこかでこれのバリエーションを見たような…。
public関数だと
/*=============
で、
private関数とかだと、
/*---------------
って感じにするの。

00166

NGNG

>>9
>それ以前に、コメントを書くのが面倒なんで、なんとかならんかと・・・

コメント入力支援機能のあるエディタかIDEを使うのが正解だと思う。
コメントのつけ方で悩んでいる場合は、とりあえずドキュメント生成ツールを開
発チームで導入して、コメントの書式を統一するところから始めてみては？
ドキュメント生成という目的があればコメントの入れ方の良し悪しも判断し易く
なるしね。

0017デフォルトの名無しさん

NGNG

>>9
> /* */を使うと、まとめてコメントアウトしたりするとき面倒だし・・
ネスとする可能性がある場合には #if 0 使うと良いよ。

0018デフォルトの名無しさん

NGNG

>>9
>それ以前に、コメントを書くのが面倒なんで、なんとかならんかと・・・

仕様書の関数定義をそのままこぴればいいんじゃないの？

VISIOあたりでクラスの記述してあればメソッド定義ごとコメントも生成される。

0019デフォルトの名無しさん

NGNG

矩形選択、矩形挿入できるエディタをつかえばー？

0020ラジャ・ライオン

NGNG

俺もコメントなんとかしたいと思ってた・・・

よし、１からコメント入力支援ソフトを作ろうっ！

とりあえず、VCとC++Builder持ってるけど、やっぱBuiderでサクッと作ってみよう。
しばし待て

0021デフォルトの名無しさん

NGNG

Cで、

return-type funcname(params)
/*
　　ここに説明
　　　　　　　　　　　　　　　*/
{
　　　処理
}

0022　　

NGNG

>>1
プログラム仕様書を自動生成するアプリケーションの仕様によるだろ

0023　　

NGNG

>>16さんのいうとおりだよ>>1

0024デフォルトの名無しさん

NGNG

モニタに油性で書きこんでます

0025デフォルトの名無しさん

NGNG

>>24
スクロールするときはどうするんですか？

0026デフォルトの名無しさん

NGNG

>>25
常に関数仕様がわかるので重宝してます。

0027デフォルトの名無しさん

NGNG

何も書かない、というか、書かないといけないような仕様に問題があるのでは？
…というのは建前で、スピード命のコードだと言い訳書かないといけないことも
あったりするんだよな。
でも、嘘コメントよりは糞コードの方がまだまし。

0028デフォルトの名無しさん

NGNG

>>27
コメント甲斐とかないと、あとでこわいおにーさんに呼び出されるじょ。

0029デフォルトの名無しさん

NGNG

>>27
コメント書かないといけないような仕様やコードもアレだけど、「数ヶ月前の
自分のコードは他人のコード」というように、コードの理解に無駄な時間をか
けないようにコメントを書くんだと思う・・・

0030デフォルトの名無しさん

NGNG

>>29
コメントを書かないと理解できないコードを書くって事にそもそも問題が
あるんだが。

ただ、往々にしてそういうコードを書かざるを得ない状況もある訳で、
そーゆー所にこそ「なぜそういう事をしてるのか」というコメントを
書けばいい。後はいらん。

まぁ品管がおばかだと何が何でも入れされられたりして鬱になるけど。
# 入れないと検収しねえとか言われたら、そらしょーがねー。

0031　

NGNG

>>30
そうなんだけど、１年後、２年後、...ｎ年後に見る場合、
実際わからねーよ。

0032デフォルトの名無しさん

NGNG

>>30
俺は、公開する関数／変数にはコメントをつける。

- 前提条件として、何か別の処理が必要？　（たとえば渡す配列はソート済みであることが要求されているとか）
- ポインタとして NULL を渡して良いのか？　その場合の動作は？

とかはコメントに書かんと分からんもの。

それにいくら「コードを読めば分かる」とはいえ、関数が出てきたときに、いちいちその関数のコードを読んで理解
するのは、規模が大きくなると時間的に厳しくなる。個人的には、開発中のコードすべてに目を通して把握できる
のは C で数万行、それ以上になると他人がメンテナンスしているコードまで把握しつづけるのは、現実の開発ペー
スだと無理だなぁ。（開発が凍結されてるコードを読んで理解しろという話なら、もうちょい行けるが）

ただ、コードのステートメントに対しては基本的にコメントをつけない。こっちは「読めば分かる」ように、変数名や
関数名で処理内容を語らせて、トリッキーな記述はマクロなんかに押し込める。どうしてもコメントをつけないと意
図不明になる場合には「こう動く」ではなくて「こういう意図でコードを書いた」と記述しておく。「こう動く」というコメン
トだと、後でコードを読んだときにバグなのか意図してのコードなのか判断しづらいんで。

0033デフォルトの名無しさん

NGNG

javadoc/doxygenどちらも試したことない奴は
一回触っといたほうがいいよ

0034デフォルトの名無しさん

NGNG

そういや、仕事でコメントがまったく書いていないスパゲッティコード
（同じ処理をコピペで何箇所も貼り付けてあったりした、関数化してく
れよ・・・）の引継ぎをして、泣きそうな目にあったことあるな・・・

後を継ぐ人の事を考えてコメント書け。

0035デフォルトの名無しさん

NGNG

>（同じ処理をコピペで何箇所も貼り付けてあったりした、関数化してく
>れよ・・・）の引継ぎをして、泣きそうな目にあったことあるな・・・
コピペ好きな人って多いよね。
俺も2chでやるのは大好きだけど、コードではな…

0036デフォルトの名無しさん

NGNG

>>32
正論。

0037デフォルトの名無しさん

NGNG

>>20
ラジャ・ラオイン期待age
はよ、うぷしれ。

0038デフォルトの名無しさん

NGNG

規約で決まるたぐいの話だな。

0039コメントは書かない！

NGNG

void kensak_wo_suru_func(char*kokokarasagasimasu,char*mitsuketaimojiretsu){

0040デフォルトの名無しさん

NGNG

>>39
なぜ strstr() を使わないのかと小一時間問い詰めたいな。標準関数は「コメントを書かなくても良い」
（自分が書くまでもなく、公式なドキュメントが存在する）関数だから、積極的に使うでしょ。

>>38
仕事だと、そういうケースも多いね。

ただ規約も上から降ってくるとは限らんし、自分が規約を作る羽目になることもある。どういうコメントを
つければ作業効率が上がるのか考えてみるのは、それなりに実があることと思われ。（腐った規約に
対して反論する武器にもなるしね）

0041デフォルトの名無しさん

NGNG

void fairu_no_kesikomi_syori_wo_kidou_suru_purosijya(char* filename){ unlink(filename) ; }

004224

NGNG

モニタがすく真っ黒になんのな

0043デフォルトの名無しさん

NGNG

perl のjavadocみたいなのないですか？

0044デフォルトの名無しさん

NGNG

>>39,>>41
むちゃくちゃ読みづらい。

0045デフォルトの名無しさん

NGNG

int　立方体の高さを計算します(int たての長さ,int よこの長さ,int うえの長さ){
_asm{
popl %eax,%ebx,%ecx
:

0046デフォルトの名無しさん

NGNG

>>40

激しく同意。
ハンガリアン変数命名法ってのも、他ではボロカスに叩かれてるけど、
俺はいいと思うんだけどなぁ・・・

//フォント情報
int nFontSize;
string strFontName;

みたく、nとかstrくらいだったら邪魔にならんと思うのだが・・・

0047デフォルトの名無しさん

NGNG

>>46
>ハンガリアン変数命名法ってのも、・・・

同意。
入力補完機能付きの環境だと候補が山ほど出てくるという弊害を指摘する人もいる
けど、グローバルな宣言を減らせば済む事だと思う。
コンパイラの型チェックがいくら強力になっても、コードの可読性にはあまり関係
の無い話だしね。

>nとかstr

どうせハンガリアンするなら潔く全部3文字に統一しては？

＃「MSが好んで使うから」というだけで嫌っている人もいるらしい。

0048デフォルトの名無しさん

NGNG

MSすら見放した時代遅れなハンガリアンの
メリットをあえて論じたいなら別スレ立ててやってくれ。

0049デフォルトの名無しさん

NGNG

>>47
> ＃「MSが好んで使うから」というだけで嫌っている人もいるらしい。
.NET ではハンガリアン使うなと MS が言ってるらしい...

0050デフォルトの名無しさん

NGNG

>>47
>コンパイラの型チェックがいくら強力になっても、コードの可読性にはあまり関係
>の無い話だしね。

ハンガリアンでべつに読みやすくなったりるとは思えないけどね。

0051デフォルトの名無しさん

NGNG

>>47
>＃「MSが好んで使うから」というだけで嫌っている人もいるらしい。

ネットでたまに見る、ハンガリアンを絶賛してる人は、
MSの(古い)コードしかしらないような人が多いね。

005248

NGNG

ほらみろ。
2chでハンガリアンの話をするとこういうことになるのだ(藁

0053いうまでもなく

NGNG

コメント以前にわかりやすい関数名・引数名を考案することのほうがはるかに重要。
コメント不要がいちばんいいのだ。

0054デフォルトの名無しさん

NGNG

>>53
話がループしてるな。

0055デフォルトの名無しさん

NGNG

コメント不要
説明は全てドキュメントに記述する。
これ最強。

0056デフォルトの名無しさん

NGNG

>>55
ドキュメントとソースコードの同期が取れなくなるという罠。

javadoc, doxygen は「それほど手間をかけずに」「そこそこのドキュメントが」書けるのが良いところ。

0057デフォルトの名無しさん

NGNG

つーか、修正したらコメント書くように促し、注意してくれる
秘書を一人雇うといいかもしれん。

0058デフォルトの名無しさん

NGNG

かわりにコメント入れてくれる秘書が欲しい

0059デフォルトの名無しさん

NGNG

関数一つにつき秘書が一人付き手とり足とり教えてくれるのがｲｲ！

0060デフォルトの名無しさん

NGNG

>>58

コメント無しのソースを理解してコメントを入れてくれるような人は秘書にはもったいないな。

0061デフォルトの名無しさん

NGNG

このスレは、
「秘書を一人雇うコストについて話し合うスレ」
になりました。

0062デフォルトの名無しさん

NGNG

派遣で秘書を雇うとすると、
時給1200～1600ぐらいか。

0063デフォルトの名無しさん

NGNG

ねぇちゃんと一緒のXPプログラミングしてぇ。

0064デフォルトの名無しさん

NGNG

批判的なコメントを書く。
これ最強。

0065デフォルトの名無しさん

NGNG

ci コメントで日記を書く

0066デフォルトの名無しさん

NGNG

コメントは、五七のリズムが基本です。

0067デフォルトの名無しさん

NGNG

>>66
　あー、俺、七五調派だよ。

// 画面のロックを解除する
// 演奏ファイルを保存する
// そもそもオープンしていない

　ってな感じで。まあ、七五調に出来るのはほんの数％しかないけどね。

0068デフォルトの名無しさん

NGNG

関数コメントも含むファイルフォーマットで以下のURLのが
結構いいと思った。他にもあれば教えてください。
http://www.cpnet.co.jp/gfan/techdoc/dev/dev01/sub.htm

0069俺はこうかな

NGNG

/*****************************************************
関数名
引数
引数
戻値
*****************************************************/

でもほかのPGから判り肉いって言われた。

0070デフォルトの名無しさん

NGNG

コードがドキュメントだ。
バグも機能もすべてかかれている。

0071デフォルトの名無しさん

NGNG

>>70
でもさー、コメントふってないと書いた人間が
「どーゆーつもり」でその処理を書いたかって
読み取れないじゃん。

無駄な事やってんのか、
副作用を期待してるのか、
副作用を避けようとしてるのか？
単なる好みの問題なのか、とか。

0072デフォルトの名無しさん

NGNG

まず関数名をコメントに書く意味はないと思う。書いてしまうと本体と同期させなくては
行けない手間が発生する。
引数や戻り値の型も書くと同期の手間が発生するので書かない。で、
　//----------------------------------------------------*/
　// 正当性チェック
　// 引数 row -> 正当性チェックしたい行番号
　// 戻り値 Validなら true
　//----------------------------------------------------*/
　boolean isValid(int row)

とかなるのだが、こうなると
　//----------------------------------------------------*/
　boolean isValid(int row)

でも変わらない気がする。(関数と関数の間に目立つ記号は残しておく)
もちろんコメント書かないとわからんような条件はコメントにするけど、結局そう
いった条件をなくしていくことがコードの洗練なわけで、自分でもがんばったときには
ほとんどコメントがないコードが出来上がっている。

0073デフォルトの名無しさん

NGNG

>>72
ちゃんとコメント書いてれば、javadocなどのツールで仕様書を
自動生成してくれるというメリットもある・・・

0074デフォルトの名無しさん

NGNG

つか、javaならプロトタイプ宣言やヘッダファイルないからいいんだけど、
C++だとヘッダと実装２つのファイルに別れてしまう。
関数コメントって、ヘッダと実装部どっちに書いた方が良いのか迷う時が
ある、両方に書く方法もあるが・・・
みんな、どっちに書いてる？
ちなみに俺は実装部のみにコメント書いてる。

0075デフォルトの名無しさん

NGNG

俺も実装部っす。

0076デフォルトの名無しさん

NGNG

私はヘッダに書いてます。

1 クラスそのもの
2 メンバ変数
3 純粋仮想関数

についてのコメントは実装部分に書きようがないし。

0077デフォルトの名無しさん

NGNG

関数ヘッダに関数名書いても、その数行下におなじこと書いてあるのでいらない。
public, private で目印つけても、やはりすぐ下に同じこと書いてあるのでいらない。
装飾付けると、肝心のコードが埋もれるのでじゃま。

/*(^_^)/(^_^)/(^_^)/(^_^)/(^_^)/(^_^)/(^_^)/(^_^)/(^_^)/(^_^)/(^_^)/
suujidesuka(char a) - 文字 a が数字'0'-'9'かどうか調べる
☆戻り値☆
数字なら TRUE を返す。
(-_-)b(-_-)b(-_-)b(-_-)b(-_-)b(-_-)b(-_-)b(-_-)b(-_-)b(-_-)b(-_-)b*/
char *eijikana(int a) { return isalpha(a)? "TRUE" : NULL; }
// ☆☆☆☆☆☆☆☆☆ suujidesuka() ここまでで～す。☆☆☆☆☆☆☆☆☆☆

とかいう定義があったら泣くだろ？俺は泣いたよ。

0078デフォルトの名無しさん

NGNG

>>77
関数コメントより、"TRUE" を返している事の方が泣けそう

0079　

NGNG

関数名が説明になってれば、コメントいらないよね～。
コメントよりもコード読んだ方が速い。

0080デフォルトの名無しさん

NGNG

>>77
全部消せっ　　ｗ

0081デフォルトの名無しさん

NGNG

>>77
部下にそんなコード提出されたら、何も言わずに殴るな。

0082デフォルトの名無しさん

NGNG

>>77
/**
* 文字が数字 (0 - 9) かどうかを調べる。ロケールは考慮しない。
*
* @param c
* 　評価する文字。ただし文字は EOF, もしくは 0 から 255 の範囲にあることを前提にしている。
*　 char が符号付きの環境では符号拡張に注意すること。
*
* @return
*　　文字が数字であれば TRUE, 数字でなければ FALSE を返す。c が範囲外の場合の動作は未定義。
*/
BOOL my_isdigit(int c);

私は、この程度は書いて欲しいなぁ。

あと人の書いたソースの保守を頼まれた場合、使えそうな関数があるのかどうか探すときにコメントがないと
厳しい。ソースを読めばわかるといっても規模が大きくなると現実的じゃないし、木を見て森を見ずになる恐れ
があるのが難だ。

008377

NGNG

>>81
部下からじゃないよ。だいぶ前の話だけど、改造請け負って実機から
引き上げて来た実働ソースの中にあったよ。
ばれるとイヤだから変えてあるけど、顔文字と全角記号の羅列で目が
チカチカした。
途中で別の会社が改造しているらしくて、そこだけややまともなコメント
で逆の意味で涙がでた。

>>78
"TRUE" も実話。類似品に "NULL" って、NULLじゃないじゃん(TT
#undef TRUE
#undef FALSE
#define FALSE 1
#define TRUE 0
なんてのもあったなぁ。「罠」ネタですね、すんません。

0084デフォルトの名無しさん

NGNG

みんな顔文字に騙されてるが、
関数名がsuujidesukaってのもかなりすごいぞ。

0085デフォルトの名無しさん

NGNG

>>83
>#undef TRUE
>#undef FALSE
>#define FALSE 1
>#define TRUE 0
何の為？

0086ナイコンさん

NGNG

doxygen+Graphvisでドキュメント作ると
クラス階層図のクリック位置がえらくズレてる。
なぜじゃ。。

0087あぼーん&rlo;んーぼあ&rlo;

NGNG

嫌でもコメントを読むハメに。
/*********************
コメント
{
　　処理
}
**********************/

0088デフォルトの名無しさん

NGNG

/******************************
* 関数名
* <Entry>
* 第１引数 : 説明
* 第２引数 : 説明
* <Return>
* 返す値の説明
******************************/

0089デフォルトの名無しさん

NGNG

>>87
意味不明

009077

NGNG

>>85
知らん。想像では、
試験段階になって仕様が逆になっているのが発覚。 →手抜き
だと思うけど、、
失敗した時の判定で、
if (! hogehoge()) return FALSE;
の '!' を書くのが面倒だったとかで無い事を祈る。

とりあえず、個人的に気をつけている、指導している例。
a) 関数の動作について簡単な説明(１～２行)
b) 各引数の意味。および制約条件
c) 戻り値の意味。値とその意味のペアが明確であるように書く。
d) 投げられる例外の種類と、投げられる状況。
e) ここまでで明確でなければ、詳しい捕捉事項。
(制限、主な使用目的、本来の目的以外に発生しうる副作用、
呼び出し方の例等など)
f) 見れば判るので、"関数名："や、"説明："といった情報料０の見出しは省く。
g) 情報の不整合を回避するため、シグネチャを見れば判る内容は省く。
h) 書式は可能であれば javadocやdoxygen等のレポートジェネレータ
が処理可能な形式で。さもなければ perl 等で関数一覧が作れる
様にマークアップする。(この場合は一覧を作るスクリプトをソースに
添付)
i) 装飾 /******** や ☆☆☆ などの装飾は、情報料０以前に邪魔になる
ので避ける。特に目の健康の為、全角記号は厳禁。
j) 関数内に付けるコメントは、1;動作の本質にかかわる部分 2; 直感的でない操作
を捕捉する形で付ける。
k) 複雑な内容を説明する場合、箇条書きでよいので、とにかく人が判るように書く。
うぅ。長い。。。若い連中が覚えられないのもうなずける。。

0091デフォルトの名無しさん

NGNG

>>87

処理のところにコメントを入れられないな。

0092デフォルトの名無しさん

NGNG

めっちゃ詳しいコメント書く奴が居て信じきってたら
bool値入れ替えてやがった
殺すぞヴぉけ！！！！！
ああ腹立つ

0093デフォルトの名無しさん

NGNG

コメントはsuujidesukaなのに、実はeijikanaで逆の意味なのが、のけぞるほどステキ（はーと）

0094デフォルトの名無しさん

NGNG

英字かどうか調べてTRUEという文字列を返すことが必要な時ってどんな時だろう？
ただの判断ならisalpha()で十分だよな。

0095デフォルトの名無しさん

NGNG

// hex_to_int
// １６進数文字をint値に（それ以外の文字はゼロ）
int hex_to_int(char c)
{
　（略）
}

ん～・・・コメントに関数名書くのは無駄かなぁ。
コメントは色変わるから、ぱっと見つけれていい感じなんだけど。
こんな簡単な関数にコメントは要らんという説もあるけど、そこは他とのバランスというか、関数によってコメントあったりなかったりというのもどうかと。

>>82 みたいな長いコメントは滅多に書かないな・・・。基本的に手抜き説明。

コメントよりコード読んだ方が速いってことは、あんましないかと（間違ったコメント書いてない限りは）。なんつっても日本語だし、概要を把握するにはコメントあった方が助かる。
でも自分で書いたコードなら、コメントなしでも、機能とか大体覚えてるからなー。なくても良いのかも。

あ、でも >>77 みたいな、インライン展開できそーな短い関数はコメント書かないな。

0096デフォルトの名無しさん

NGNG

>>95

strtol()でいいじゃん。

たとえばの話？

0097デフォルトの名無しさん

NGNG

>>95
int hex_to_int(char c) ←ここんとこも色変えればいいやん。

009895

NGNG

>>96
文字列中のエスケープシーケンス（\x00とか）の読み取りで使ってるヤツで、桁数が固定なんよ。strtol だと、読めるとこまでいくらでも読んでいくじゃない？・・・って、どうでもいい話。

>>97
うぅ。某乱度のエディタは、そういうとこは色を変えてくれないんよ。

0099デフォルトの名無しさん

NGNG

sscanf()使え

010095

NGNG

>>99
そういう議論をするスレじゃないから却下。

0101デフォルトの名無しさん

NGNG

>>100
sscanf()使えばコメントつける関数ごと不要になる。

0102101

NGNG

…たしかにどうでもいい話だが。

0103デフォルトの名無しさん

NGNG

つか、コメント支援がついてるエディタかIDEってどんなのある？

0104けいとく

NGNG

>>103
たいていのエディタならテンプレート挿入機能はついてるよ。
emacs か xyzzy 使っとけ。

「ヒント22: ひとつのエディターを熟知すること」
　　　　　　　　　　　　『達人プログラマー』 P.82

■ このスレッドは過去ログ倉庫に格納されています