コメントの記入の仕方

質問

先輩（既にいませんが）のマイコンのプログラムを見てコメントが全部英文（または英単語）で書いてあり「これ本人わかるのか？」と思いました。それも部分によっては一行ごとに記入してあるのでかなり見難い。
コメントはプログラムを理解しやすくする為に記述するものかと思うのですが書いてある内容を理解するよりアセンブラの本文を理解するほうが早いのでは？と思う始末。
実際にコメントはどちらで書く事が多いのでしょう？私自身それほど熟練では無いので日本語コメントの方がありがたいですが。（簡単な単語は別ですけど。）
日本語コメントだと変換がめんどくさいでしょうけど。
ちなみにその先輩はプログラマーが本業ではありません。

回答No.5

KCTW

すでに皆さん書き込まれてますが経験から言えることを。

僕のまわりでは英語でコメントを入れる人が多いです。
中には(他人が書いたソースの)日本語のコメントを全て英語に書き直して使ってる人すらいます。理由としては、

・開発環境の文字コードの相違による見づらさを回避するため
・何の疑問もなく英語で書く(プログラム言語自体英語ベースだから)

の二通りが多いようです。まぁ研究者達は英語もペラペラなのでそれで困らないのでしょう。
僕はやはり日本語で書きます。
ただ、プログラムの冒頭にプログラムの概要やパラメータ等の情報を書くときは英語で書きます。
これは自分がEUC-JPとUTF-8の環境を行き来する時にそこが分からないと最低限不便だからです。
あ、あと、友人にはカッコつけて誤った英文法でコメントつけてるやつもいますけど(笑)

お礼

確かに英語がぺらぺらなら何も気にする事ないですよね・・。
その辺の問題なのかもしれないですね。回答ありがとうございます。

回答No.4

nekonokota

私が行ったCOBOLの現場で、コメントは、
----------------------
○○を××する
85.02.07 Ver.1 作成者
----------------------
こんだけ。っていうケースがありました。その後ソースが150行ぐらい。
辞めましたけど（笑）

統合開発環境（身近なところで行くと、Visual C# Express Editionとかかな）は、自作のクラスのメソッドなどに、所定の方式のコメントを入れる（XML文を記入する、のが正しいのか？）と、その自作クラスを使うときに、入力補完ができるようになったりしているので、つけておいて大損する、と言うことはないと思います。

私は鳥頭（≒３歩くと忘れる）なので、多少の手間がかかっても、入れるようにしています。

（現ホビープログラマより）

お礼

回答ありがとうございます。あまりに少なすぎるのも問題ですね。
コメント記入もプログラム同様に個性なんでしょうか。

回答No.3

buriburi3

自分で作ったプログラムでも半年、1年、2年とたてば内容なんぞサッパリ覚えてなくて他人が作ったも同然の状態になります。
コードを読めば何をやってるかわかるような事をコメントに書く必要は無いです。
コードを読んでも分からないであろう事情や意図を書いておくと良いです。

お礼

時間経つと覚えていないですよね。少なくとも見出しくらいはわかるように書いてくれよというくらいわかり難いもので、目を通す気にもならないくらいでしたから。
要点だけですよね。回答ありがとうございます。

回答No.2

noname#194317

まあ普通は日本語で書くでしょうけど、マイコンだと開発環境によってはASCII文字しか使えないこともあり得るので、その場合はいやでも英語で書くしかないでしょうね。ローマ字という手もありますけど、それじゃあどっちもどっちな気が…

コメントは自分が解ることがまず優先、他人のことは考えないのがありがちなパターンですが、そうすると得てして、時間が経つと自分にも解らなくなります。「なんて解りにくいことしてんだよ、昔の俺」っていう悲しい（しかしよくある）オチになります。

中には日本人なのに、コメントは全てロシア語で書くという変人もいるようですが、やはりコメントは他人に読まれることを前提として書くべきでしょうね。

お礼

やはり日本語の方がわかりやすいですよね。
確かにコメントに時間を割くのも馬鹿らしいので多少手抜きで後からなんだっけ・・という事はありますけど。
他人がわかるように書くことを心がけたほうがいいですね。
回答ありがとうございます。

回答No.1

trajaa

誰のためのコメントか？でしょう。
自分自身の為なら自分自身が見やすければ何でもアリだろうけど。

既に居ないと言うことは引き継いだと言うことか？
引き継ぐと言うことは、個人的になモノでなく業務としてなのかな？
なら、自分以外には分からないようなコメントは意味が無いですね。

まあ、マイコンとの事、アセンブラとの事ですから
普通の業務系とは、同列には語れない点はあるにしても・・・・

コメントには、初期定義の意味とか、処理分岐の意味とかコードステップ単行よりも上のレベルでの概略が掴めるようなのが必要
あまり細かく書かれても、それじゃ各行を逐次解釈するのと一緒ですなぁ

と、私は思うけど。

お礼

まずは自分でわかるようにですよね。ただあまりにも見難いので本人もわかるのかなと思うのです。（あまりできる人ではなかったのでカッコつけて書いていたのかなとも思いますけど）
肝心な部分にコメントが少なくどうでもいいような部分に一杯かいてあるので余計にです。回答ありがとうございます。