web-dev-qa-db-ja.com

PHP：コメント標準

ほんの一握りのファイルで大量の情報にコメントする必要があります。GoogleとここSOを見てみると、コメント基準が必要なときにcoding standardsに一致する結果が見つかります。私のコーディングは、コメントの場合を除いて、ほとんどのコーディング標準に一致しています。

誰かが次の例を提供できますか？

<?

    // beginning of file comments

    require( 'filename.php' ); // require or include, with filename

    public class Test { } // class without constructor

    public class Test // class with constructor, if different from above
    {
        public function __constructor() { } // constructor, no parameters

        public function __constructor(var1, var2) { } constructor, with parameters

        public function func1() { } // function, no parameters

        public function func2($var1, $var2) { } // function, with parameters

        public function func3( $optional = '' ) { } // function, optional parameters

        private function func4() { } // private function, if different from above

        public static staticfunc1() { } // public static function, if different from above

        public function returnfunc1(var1, var2) // function, with return value
        {
            return var1 + var2; // return statement, dynamic
        }

        public function returnfunc2() // function, with unchanging return value, if different from above
        {
            return 1; // return statement, unchanging, if different from above
        }

        public function fullfunc1() // declaration, calling and assignment, in function
        {
            $var1; // variable declaration

            $arr1 = array(); // array declaration, if different from above

            $var2 = dirname( __FILE__ ) . '/file.ext'; // variable assignment

            $this->var1 = $path . '_'; // class variable assignment

            ob_start(); // function call

            $this->func1(); // class function call

            ob_end_clean();

            foreach($arr as $key => $val) { } // foreach and for loops
        }

        public $var1; // public variable

        private $var2; // private variable, if different from above
    }

    // ending of file comments?

?>

適切なスタイルを知ることは重要です。それは他の人があなたのコードがどのように機能するか、そしてあなたがそれを説明するためにそこにいない場合にそれを将来どのように使うかを理解するのを助けます。

phpcoding-stylecomments
12
Brian Graham

一般的に、PHPにはさまざまなスタイルガイドがあるようです...

  1. phpDocumentorスタイル
  2. Zend Frameworkスタイル
  3. 洋ナシスタイル

しかし、一般的に、コメントについて覚えておくべきことは...コードのすべての行にコメントしたくないでしょう。代わりに、コードを読みやすくするようにしてください1 （そのままです。）そして、コードが何をしているのかを理解するために他の誰かが本当に必要な場合は、（ほとんどの場合）コメントします。

1http://www.codinghorror.com/blog/2008/07/coding-without-comments.html

18
summea

http://www.kevinwilliampang.com/2008/08/28/top-10-things-that-annoy-programmers/ から取得

「理由」ではなく「方法」を説明するコメント

入門レベルのプログラミングコースでは、学生に早期にコメントし、頻繁にコメントするように教えます。コメントが少なすぎるよりも多すぎるほうがよいという考えです。残念ながら、多くのプログラマーは、これをコードのすべての行にコメントする個人的な課題と見なしているようです。これが、コメントなしのコーディングに関するJeffAtwoodの投稿から抜粋したこのコードスニピットのようなものをよく目にする理由です。

r = n / 2; // Set r to n divided by 2
// Loop while r - (n/r) is greater than t
while ( abs( r - (n/r) ) > t ) {
    r = 0.5 * ( r + (n/r) ); // Set r to half of r + (n/r)
}

このコードが何をするのか分かりますか？私もダメ。問題は、コードが何をしているのかを説明するコメントはたくさんありますが、なぜそれをしているのかを説明しているコメントがないということです。

ここで、異なるコメント方法で同じコードを検討します。

// square root of n with Newton-Raphson approximation
r = n / 2;
while ( abs( r - (n/r) ) > t ) {
    r = 0.5 * ( r + (n/r) );
}

ずっといい！ここで何が起こっているのかまだ正確には理解できないかもしれませんが、少なくとも出発点はあります。

コメントは、読者が構文ではなくコードを理解するのに役立つはずです。読者がforループの仕組みを基本的に理解していることは当然のことです。 「//顧客のリストを繰り返し処理する」などのコメントを追加する必要はありません。読者がなじみのないことは、コードが機能する理由と、コードを自分のやり方で書くことを選択した理由です。

また... phpdoc

10
David Chan

PHPのコメントは、想像以上に自由なスタイルです。ただし、本当に特定のコメント標準が重要になる理由は、開発をスピードアップするために特定のIDEとどのように相互作用するかによるものです。その場合、IDEがどのようにコメントを求めているかを調べることができます。

重要なのは、通常、@ paramの関数と@returnの関数をマークすることです。

このスタックオーバーフローの質問と回答で、適切なコメントに関するいくつかの良い情報を見ることができます： 適切なPHP関数のドキュメント形式は何ですか？

0
Kristian