Inline documentation for classes should follow the PHPDoc
convention, similar to Javadoc. More information about PHPDoc can
be found here: http://www.phpdoc.org/
Non-documentation comments are strongly encouraged. A general rule of
thumb is that if you look at a section of code and think "Wow, I don't
want to try and describe that", you need to comment it before you
forget how it works.
C style comments (/* */) and standard C++ comments (//) are both
fine. Use of Perl/shell style comments (#) is discouraged.
