質問をすることでしか得られない、回答やアドバイスがある。

15分調べてもわからないことは、質問しよう!

ただいまの
回答率

91.37%

  • PHP

    15139questions

    PHPは、Webサイト構築に特化して開発されたプログラミング言語です。大きな特徴のひとつは、HTMLに直接プログラムを埋め込むことができるという点です。PHPを用いることで、HTMLを動的コンテンツとして出力できます。HTMLがそのままブラウザに表示されるのに対し、PHPプログラムはサーバ側で実行された結果がブラウザに表示されるため、PHPスクリプトは「サーバサイドスクリプト」と呼ばれています。

  • プログラミング言語

    560questions

    プログラミング言語はパソコン上で実行することができるソースコードを記述する為に扱う言語の総称です。

  • コーディング規約

    38questions

    コーディング規約とは、コードの書き方についての決め事のことです。 文法のことではなく、そのチームなどの中の約束事としてどのような書き方で行うかを定めるもの。 項目の例として、関数や変数の命名規則、コーディングのスタイル、括弧やインデントの書き方などが挙げられます。

コメントの量に関して

解決済

回答 8

投稿 2017/11/29 13:04 ・編集 2017/11/29 13:06

  • 評価
  • クリップ 4
  • VIEW 301

ERINGI5

score 14

答えの無い質問となってしまいますが
開発の際どれくらいコメントを残してますか?

個人的にはソースコードから読み取れない処理に関してはコメントを入れるべきだと思いますがそれ以外はメソッド名や変数名の付け方で頑張った方いいと思ってます。
しかし、私のチームでは全てのメソッドにコメントを付けることが義務付けられています。
CakePHPでいうところのAction名にもコメントを付けるように言われているのですがどう思いますか?

できればコメントを極力書かない習慣にしたいのですが、説得させる情報が無いため色々とご教授いただけますでしょうか。

  • 気になる質問をクリップする

    クリップした質問は、後からいつでもマイページで確認できます。

    またクリップした質問に回答があった際、通知やメールを受け取ることができます。

    クリップを取り消します

  • 良い質問の評価を上げる

    以下のような質問は評価を上げましょう

    • 質問内容が明確
    • 自分も答えを知りたい
    • 質問者以外のユーザにも役立つ

    評価が高い質問は、TOPページの「注目」タブのフィードに表示されやすくなります。

    質問の評価を上げたことを取り消します

  • 評価を下げられる数の上限に達しました

    評価を下げることができません

    • 1日5回まで評価を下げられます
    • 1日に1ユーザに対して2回まで評価を下げられます

    質問の評価を下げる

    teratailでは下記のような質問を「具体的に困っていることがない質問」、「サイトポリシーに違反する質問」と定義し、推奨していません。

    • プログラミングに関係のない質問
    • やってほしいことだけを記載した丸投げの質問
    • 問題・課題が含まれていない質問
    • 意図的に内容が抹消された質問
    • 広告と受け取られるような投稿

    評価が下がると、TOPページの「アクティブ」「注目」タブのフィードに表示されにくくなります。

    質問の評価を下げたことを取り消します

    この機能は開放されていません

    評価を下げる条件を満たしてません

    評価を下げる理由を選択してください

    詳細な説明はこちら

    上記に当てはまらず、質問内容が明確になっていない質問には「情報の追加・修正依頼」機能からコメントをしてください。

    質問の評価を下げる機能の利用条件

    この機能を利用するためには、以下の事項を行う必要があります。

質問への追記・修正、ベストアンサー選択の依頼

  • yambejp

    2017/11/29 13:14

    「できればコメントを極力書かない習慣」にしたい理由はなんでしょか?めんどくさい?ご自身は他人のコメントをみることはなかったり、見ても意味がわからなかったりするのでしょうか?他人の書いたコードなんてコメント無しでみるのはそうとう苦痛だと思いますが・・・、いずれにしろチームでやる以上ドキュメントは残すのでしょうから、そとに残しているならソースに埋め込む必要はないような気はしますが

    キャンセル

  • ERINGI5

    2017/11/29 20:56

    コメントを書く事が面倒だとか、手間がかかるとは思っておりません。コメントが書ける事によって変数名の意味や価値が薄れてしまう事を懸念しています。(書く人によりますが....)変数名を見ただけで何が代入されているか特定でき、メソッド名を見るだけで中の処理が把握できる方がベストだと思っておりました。(みなさんの意見を参考に過去形にさせていただきます。)変数名を付けるのにだいぶ悩んでいるので逆に生産性は下がっているかもしれません.........

    キャンセル

回答 8

checkベストアンサー

+6

仰るように基本的にwhy not以外書く必要はありません。
whyは不要、コード読めの精神ですね。

全てのメソッドにコメントを付ける

所謂PHPDocですね。
ツール通せばドキュメントが出来上がるので、SIerの現場等では徹底しておけばそれはそれで結構でかいメリットがあります。

他にもPHPStormではパラメータでクラスを指定しておくと、
クラスメソッドの補完が効きますし定義に飛べるようになり開発が楽になります。

まぁPHPDoc書く時はざっくりとした概要の紹介だけで十分です。
書きすぎるとメンテする時にコメントとコードを二重でメンテするはめになるので詳細は書かない方が良いでしょう。
詳細書きたければ単体のテストコードに時間掛けたほうが良いと思います。

投稿 2017/11/29 13:14

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

  • 2017/11/29 13:18

    https://twitter.com/t_wada/status/904916106153828352
    テスト駆動開発の書籍でおなじみの和田氏のツイートを紹介

    > コードには How
    > テストコードには What
    > コミットログには Why
    > コードコメントには Why not
    > を書こうという話をした

    キャンセル

  • 2017/11/29 13:28

    質問文の状況に於ける私の考えとしては、
    前提の「なんでPHPDocを書かなきゃいけないの?メンバーがIDEで利用したり、ドキュメントにして客に出してるの?」辺りはチームで確認とっても良いとは思います。
    その結果、チームの判断がメリットがデカイからPHPDocを残すと決定したのであれば従うべきでしょう。

    キャンセル

+5

引数の意味や返り値など、どんなメソッドでも必要になるようなものを書くPHPDocという記法がありますので、義務付けられているのであればそれに従って書くのが最適解かと思います。

PHPStormやNetBeansなど、PHPに対応したIDEの場合、PHPDocから情報を読み取って、メソッド呼び出しのところでポップアップ表示したりというような機能があります。

投稿 2017/11/29 13:15

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

+5

できればコメントを極力書かない習慣にしたい

コメント不要論には、何か根底に誤解がある気がします。
コメントが減るのは結果であって、減らすのが目的ではないです。

もし、交通事故の多い場所に、「この先急カーブ」とか看板が多いとして、
たんに看板をなくしても、事故は減りません。むしろ増えるでしょう。
あるいは、咳を我慢したら風邪が治るか、ということです。

だから、リファクタリングなどによって、コメントの必要がなくなり、
結果的に減るのは良いです。コメントだけ消してもダメです。

しかしここで、現実問題として、リファクタリングする時間がないことも多く、
それならせめてコメントを残しておいてくれれば、
問題を探す時間や、うかつに変更して出たバグを潰す時間の浪費を避けられます。

コメントを書くのは多くの場合で最善ではないですが、基本的に善です。
コメント自体は、根本的解決でなく、対処療法的な手段ですが、
たんにそれを書かないのもまた、表面的な解決に過ぎません。


メソッド名や変数名の付け方で頑張った方いいと思ってます

それでもコメントにまだ抵抗があるとしたら、こう考えてください。

コメントは最終結果ではなく、リファクタリングの過程だと考えます。

何か難しい、分かりにくい、問題のある処理があったときに、
最初はまずコメントを書いてみる。実装コストが安いので気軽に試せます。

根本的な問題があると思った場合、コメントのままにせず、
さらに、説明的な変数にする、メソッドに切り出す、クラスに分ける、
ライブラリ化する……などと、より大きな単位にしていく場合があります。

つまり、コメントを書かないというより、コメントを書いて、
さらに大きな単位でまとめられないかを考えます。

これを最初から大きな単位で書くと、
不要なものを作ってしまいがちです。

コメント自体を書かないことが大事というより、
コメントから先を書くことが大事だと思います。


投稿 2017/11/29 21:19

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

  • 2017/11/29 21:31

    「コメントは最終結果ではなく、リファクタリングの過程」なるほど.......
    納得できる考え方ですね。

    ご指摘いただいた通り、現状はただコメントをなくすだけで可読性の悪いソースになっている気がします。
    あくまでリファクタリングの過程と言う考え方で徐々にいいコードにできればと思います。

    ご教授ありがとうございます。

    キャンセル

  • 2017/11/29 22:06

    「テスト駆動開発」という書籍があります。
    この書籍ではテストを先に書けと説いています。
    丁度LLmanさんが本回答で説いているコメントと同じ箇所に当てはまります。

    コメントの場合、機能を実装が進むにつれ、重複の整理の為に削られる運命にありますが、
    テストコードは整頓されて多少削られる可能性はありますが、その場に全部残ります。
    (当然、テストコードの側は死ぬ気でメンテするコストも必要で、「テスト駆動開発」の本の実践をチーム全体でどこまで受け入れられるかだと思います。)

    このようにプロジェクト全体で何を何処に書くかを担保出来れば良いので、
    後はチーム全体でコメントとどう付き合っていくかだけの問題に尽きるでしょう。

    キャンセル

  • 2017/11/29 22:56 編集

    >ERINGI5さん
    >リファクタリングの過程と言う考え方で徐々にいいコードにできれば
    そうですね。コメントというと、古いスタイルに思えるかもしれませんが、
    じつは、アジャイルのように反復的な開発スタイルと相性が良いと思います。


    >miyabi-sunさん
    >「テスト駆動開発」
    そうですね、テストと似たところがあります。
    テストも「コメントから先」にあるものです。

    テストは重要です。が、コストが高いので、100%カバーするのが理想でも、
    現実的には、いかに重要な部分をカバーするか、という問題になりがちです。

    日本語の問題もあります。日本人には日本語のコストが低いので、
    日本語コメントだと、思考しやすい、注意しやすい面もあります。

    だから、つまりこうです。100%テストが書いてあって、
    コメント0%というのが、コメント不要論者が想定する理想状態です。
    でも、現実的にはそこまでする開発リソースが足りない場合も多い。

    それなら、とりあえずコメントを種のようにバラまいておいて、
    リファクタするなり、テストを書くなり、そこから育てていく
    きっかけにするのも、現実的な選択肢としてアリだと私は思ってます。

    キャンセル

+4

個人でやっている場合にはほぼ残さないですね。
ERINGI5さんがおっしゃっている程度で十分だと思います。

どこまで書く書かないという判断はそのプロジェクトによって違うと思います。
結局最終的な目的にすべきなのは生産性ではないでしょうか。

コメントを書くことで生産性が下がるなら要らない。
コメントを書くことで生産性が上がるなら書くべきだと思います。

それは個人の生産性ではなく、今だけの生産性ではなく、製造の生産性だけではなく
プロジェクト全体・納品・管理・今後の保守・運用も含めた全てを加味した上での生産性です。

基本的にはプロジェクトが大きければ大きいほど、長ければ長いほど、コメントは重要になって来ると思います。
(コーディング規約やコメントルールを守るためのコストもかかって来ますが・・・)
小さくて短いプロジェクトなら恐らく書くのは無駄です。

プロジェクトによっては納品や管理に使われている場合もありますので
1人や数人の製造コストだけを見て判断すべきものではないと思います。

全てを鑑みてもコメントを書くコストが無駄ならば、やめるべきだと思います。

が、それでも政治的なものやルールを変えるためのハードルやコストなどもありますので
トータルで考えると、プロジェクト途中でルールを変えるのはあまり得策だとは思いません。
(小さいプロジェクトならできるかもしれませんが。)

新しくプロジェクトが立ち上がる時に考えるべきことなのかなとは思います。

投稿 2017/11/29 13:41

編集 2017/11/29 14:41

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

+4

コメントに関しては、つける派とつけない派にどうしてもわかれますね。
私はつける派です。
コメントの付け方やつける理由は以下の通り。

  • 当たり前のことは書かない。aに1を代入する、とか。
    aに1を代入するということは、つまりどういうことかを書く。

  • コードを読めばわかる単純な処理でも書く。
    ある程度の処理単位でコメントを入れることで、大まかなブロックができるので、可読性が上がります。

  • 他人が見たときにわかりやすい。
    自分が書いたコードなんて他人には即座に理解できないものです。

  • 時間が経ってから自分が見てもわかりやすい。
    例え自分がわかりやすく書いたコードでも、時間が経つと忘れているものです。

  • コメントがなくて文句を言う人がいても、コメントがあって文句を言う人はいない。
    仕事としてコードを書くなら当然お客さんがいるわけですから、納品物として文句を言わせないためにもコメントは必須。

投稿 2017/11/29 14:13

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

+3

ソースコードは今後誰が読むのかわからないものですから, コメントが多いに越したことはないと思います. どうせ後から消すことも出来ますし. 
それよりも「量を減らす」のではなく「質を上げる」ほうが重要であろうかと. コメントの履歴が残るような管理は絶対にやめるべきですが, コーダーさんの意図を正確に後世に伝える目的であれば積極的に記述して良いかと思います. 

投稿 2017/11/29 13:21

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

+3

コードドキュメンタ(コード内のコメントをもとに、コード解析結果をドキュメント化するツール)のために書くコメントというのもありますので、一概にはコメントの量を云々は言えません。
JavaDoc や PHPDoc は、こういうドキュメント化のためのコメントです。

その意味では、CakePHPにおけるActionにもつけることは必要だといえるでしょう。それはすなわち、Action一覧を作る際の資料になるものだからです。

メソッドの in/out 、概要を明示するコメントは必要でしょうが、メソッド内部のロジックに絡む部分まで細かくコメントを入れるかといえば、それは入れないほうが良いでしょう。コードを読む際に補助となる程度があればよいかと思います。
例えば if 分岐で、「なぜこのif判定になるのか」を書いておくなどです。機能の詳細設計と見比べたときに、正しい if 判定をしているのかどうかわかりやすくなりますし。

投稿 2017/11/29 13:31

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

+2

私もPHPStormを使っており、PHPDocの記述もあったのでコメントはその為っぽいです。
PHPDocがあまり理解出来ておりませんでしたのでこれを機に少し調べてみようと思います。

ご回答ありがとうございました。

投稿 2017/11/29 21:07

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

15分調べてもわからないことは、teratailで質問しよう!

ただいまの回答率

91.37%

関連した質問

同じタグがついた質問を見る

  • PHP

    15139questions

    PHPは、Webサイト構築に特化して開発されたプログラミング言語です。大きな特徴のひとつは、HTMLに直接プログラムを埋め込むことができるという点です。PHPを用いることで、HTMLを動的コンテンツとして出力できます。HTMLがそのままブラウザに表示されるのに対し、PHPプログラムはサーバ側で実行された結果がブラウザに表示されるため、PHPスクリプトは「サーバサイドスクリプト」と呼ばれています。

  • プログラミング言語

    560questions

    プログラミング言語はパソコン上で実行することができるソースコードを記述する為に扱う言語の総称です。

  • コーディング規約

    38questions

    コーディング規約とは、コードの書き方についての決め事のことです。 文法のことではなく、そのチームなどの中の約束事としてどのような書き方で行うかを定めるもの。 項目の例として、関数や変数の命名規則、コーディングのスタイル、括弧やインデントの書き方などが挙げられます。