matobaa score 1910
2015/04/29 14:58 投稿
| 文法や形式については別途。「なにをどうかくか」という観点から回答します。 |
| ソースコードコメントにはいくつかの種類があります。以下、種類ごとに、どのように書いたらよいかまとめます: |
| --- |
| 1. 仕様を説明するもの |
| クラスやメソッド、関数などの利用者にむけて、これはこういうものだよ、こういう使い方をしてね、というメッセージを書きます。 |
| **各関数の前**に、「この関数は＊＊をする。＊＊、＊＊、＊＊を引数として受け取り、＊＊を返す。ゼロを返すことはない。＊＊の場合は＊＊となる。」といった要領で書きます。 |
| Doxygenなどのツールで文書化することができます。 [http://www.doxygen.jp/docblocks.html](http://www.doxygen.jp/docblocks.html) |
| --- |
| 2. 意味を説明するもの |
| ソース中に現れる、ぱっとは意味がわかりにくい記述に対して意味を補足します。 |
| - double adj[3]={0.682,0.682,0.682}; |
| という行に対し、「この 0.682 とは＊＊という意味である」ということを記述します。 |
| ほかに設計書や解説書があるなら、「画面設計書 5.6.2 の記載に基づき」のように根拠を示す方法もあります。 |
| 定数として別に定義しておき、その定数名を工夫するという方法もあります。 |
| - printf("t.dwt0b0"); |
| という行に対し、「この.dwとは＊＊という意味である」ということを記述します。……ってこれ、アセンブラコードを生成してるんですかね? そういう文脈が明らかであれば、.dwなんて説明するまでもないでしょうからコメントはいらないでしょうね。 |
| という行に対し、「この.dwとは＊＊という意味である」ということを記述します。……ってこれ、アセンブラコードを生成してるんですかね? 読む人にとってそういった文脈が明らかであれば、.dwなんて説明するまでもないでしょうからコメントはいらないでしょうね。 |
| --- |
| 3. 意図を説明するもの |
| ソース中に現れる、ぱっとは意図がわかりにくい記述に対して意図を補足します。 |
| たとえば、私は |
| - printf("t.dwt0b0"); |
| という行に対し、なぜ0bなのか疑問に思いました。 |
| - printf("t.dwt0x%x%x%xn", x[0],x[1],x[2]); |
| でいいんじゃないか、と。そこで 「0bにしている理由は＊＊である」というコメントがあれば疑問はなくなります。 |
| ほかには、その下の else 節では、単純に printf("%d,%d,%dn",x[0],x[1],x[2]); としていますが、そんなんでいいのか? と思いました。きっと仕様書のどこかどおりに書いているんだとは思いますが、それなら「仕様書 5.6.2に従い」といった補足コメントがあるとうれしいです。 |
| 古い資料ですが、 Scott W. Ambler による「Writing Robust Java Code」の一節を紹介します。 |
| [http://www.alles.or.jp/~torutk/oojava/codingStandard/writingrobustjavacode_pidid93_c1.html#doc1_id171](http://www.alles.or.jp/~torutk/oojava/codingStandard/writingrobustjavacode_pidid93_c1.html#doc1_id171) |
| > コメントには、なぜそうなのかを書く。コードを読めば分かることを書かない |
| > 基本的に、コードの一部分を見ればそれが何かを理解することはできる。 例えば、以下の例1.1のコードを見て、$1000以上の注文については5%ディスカウントされることは理解できる。なぜそうなのか？ 大きな注文ではディスカウントがつきものだというビジネスルールがあるのだろうか？ 大きな注文に時間限定サービスがあるのか、それともずっとサービスがあるのか？ これを書いたプログラマーの気前がよかったのか？ どこかソースコード中か別な文書にドキュメントされていない限り、なぜなのかを知ることはできない。 |
| --- |
| 4. ソースコード上のマーカーとして |
| 統合開発環境の中には、// TODO や // FIXME といったコメント行を見つけてブックマークリストを作ってくれたり、 //@formatter:off と書くと、それ以降はオートフォーマットしないでくれたりといった機能を持つものがあります。そういう機能を使うためにコメントを書くような場合もあります。 |
| --- |
| 「リーダブルコード」いい本ですよね。おすすめです。 |
matobaa score 1910
2015/04/29 14:57 投稿
| 文法や形式については別途。「なにをどうかくか」という観点から回答します。 |
| ソースコードコメントにはいくつかの種類があります。以下、種類ごとに、どのように書いたらよいかまとめます: |
| --- |
| 1. 仕様を説明するもの |
| クラスやメソッド、関数などの利用者にむけて、これはこういうものだよ、こういう使い方をしてね、というメッセージを書きます。 |
| **各関数の前**に、「この関数は＊＊をする。＊＊、＊＊、＊＊を引数として受け取り、＊＊を返す。ゼロを返すことはない。＊＊の場合は＊＊となる。」といった要領で書きます。 |
| Doxygenなどのツールで文書化することができます。 [http://www.doxygen.jp/docblocks.html](http://www.doxygen.jp/docblocks.html) |
| --- |
| 2. 意味を説明するもの |
| ソース中に現れる、ぱっとは意味がわかりにくい記述に対して意味を補足します。 |
| ```lang-C |
| double adj[3]={0.682,0.682,0.682}; |
| ``` |
| - double adj[3]={0.682,0.682,0.682}; |
| という行に対し、「この 0.682 とは＊＊という意味である」ということを記述します。 |
| ほかに設計書や解説書があるなら、「画面設計書 5.6.2 の記載に基づき」のように根拠を示す方法もあります。 |
| 定数として別に定義しておき、その定数名を工夫するという方法もあります。 |
| ```lang-C |
| printf("t.dwt0b0"); |
| ```という行に対し、「この.dwとは＊＊という意味である」ということを記述します。……ってこれ、アセンブラコードを生成してるんですかね? そういう文脈が明らかであれば、.dwなんて説明するまでもないでしょうからコメントはいらないでしょうね。 |
| - printf("t.dwt0b0"); |
| という行に対し、「この.dwとは＊＊という意味である」ということを記述します。……ってこれ、アセンブラコードを生成してるんですかね? そういう文脈が明らかであれば、.dwなんて説明するまでもないでしょうからコメントはいらないでしょうね。 |
| --- |
| 3. 意図を説明するもの |
| ソース中に現れる、ぱっとは意図がわかりにくい記述に対して意図を補足します。 |
| たとえば、私は```lang-C |
| printf("t.dwt0b0"); |
| ```という行に対し、なぜ0bなのか疑問に思いました。 |
| ```lang-C |
| printf("t.dwt0x%x%x%xn", x[0],x[1],x[2]); |
| ```でいいんじゃないか、と。そこで 「0bにしている理由は＊＊である」というコメントがあれば疑問はなくなります。 |
| たとえば、私は |
| - printf("t.dwt0b0"); |
| という行に対し、なぜ0bなのか疑問に思いました。 |
| - printf("t.dwt0x%x%x%xn", x[0],x[1],x[2]); |
| でいいんじゃないか、と。そこで 「0bにしている理由は＊＊である」というコメントがあれば疑問はなくなります。 |
| ほかには、その下の else 節では、単純に printf("%d,%d,%dn",x[0],x[1],x[2]); としていますが、そんなんでいいのか? と思いました。きっと仕様書のどこかどおりに書いているんだとは思いますが、それなら「仕様書 5.6.2に従い」といった補足コメントがあるとうれしいです。 |
| 古い資料ですが、 Scott W. Ambler による「Writing Robust Java Code」の一節を紹介します。 |
| [http://www.alles.or.jp/~torutk/oojava/codingStandard/writingrobustjavacode_pidid93_c1.html#doc1_id171](http://www.alles.or.jp/~torutk/oojava/codingStandard/writingrobustjavacode_pidid93_c1.html#doc1_id171) |
| > コメントには、なぜそうなのかを書く。コードを読めば分かることを書かない |
| > 基本的に、コードの一部分を見ればそれが何かを理解することはできる。 例えば、以下の例1.1のコードを見て、$1000以上の注文については5%ディスカウントされることは理解できる。なぜそうなのか？ 大きな注文ではディスカウントがつきものだというビジネスルールがあるのだろうか？ 大きな注文に時間限定サービスがあるのか、それともずっとサービスがあるのか？ これを書いたプログラマーの気前がよかったのか？ どこかソースコード中か別な文書にドキュメントされていない限り、なぜなのかを知ることはできない。 |
| --- |
| 4. ソースコード上のマーカーとして |
| 統合開発環境の中には、// TODO や // FIXME といったコメント行を見つけてブックマークリストを作ってくれたり、 //@formatter:off と書くと、それ以降はオートフォーマットしないでくれたりといった機能を持つものがあります。そういう機能を使うためにコメントを書くような場合もあります。 |
| --- |
| 「リーダブルコード」いい本ですよね。おすすめです。 |
