Are comments in CakePHP Code really even used/necessary?

Question

Reading through the core and looking at nearly all of the helpers/plugins etc. that are available, I notice there are a lot of comments.

CakePHP is structured in such a way that it is very simple to determine where things are and what they are doing. Is it really necessary to comment all of this code? Does it make the source more messy or is it really useful? When you grok the comments, do you find them useful? Or do you even read them?

UPDATE: Here is a sample of comments taken from the CakePHP Core connection manager for example:

/**
 * Loads the DataSource class for the given connection name
 *
 * @param mixed $connName A string name of the connection, as defined in app/config/database.php,
 *                        or an array containing the filename (without extension) and class name of the object,
 *                        to be found in app/models/datasources/ or cake/libs/model/datasources/.
 * @return boolean True on success, null on failure or false if the class is already loaded
 * @access public
 * @static
 */

Answer 1

Well, personally I don't need any doc-block comments to figure out what's going on. I can look at the code and in a few minutes figure out what I need to know (assuming intelligently designed code). So, from a cursory glance they do seem redundant and un-necessary, right?

Wrong. Why should I have to spend a few minutes figuring out what a method does (exactly, not from a high level) so that I can use it how I need to? That's where the documentation comes in handy. I can quickly reference a HTML generated documentation (which is generated right from the source code) to see what I need to know in a fraction of the time it would take me to look at the code itself (and looking at the code itself is pretty quick).

Now, if I am trying to push the limits of what the code was supposed to do, then yes, I may spend more time reading the code than the documentation. But in general, the docs make it MUCH faster and easier to just find what I need and move on.

Remember, you don't need to know everything. You just need to know where to find it...

Oh, and my other favorite quote, Work Smarter, Not Harder...

Note, this is assuming the documentation in question is updated and well-written.

And this is not by any means Cake specific (I have never even used Cake)...

Answer 2

Comments, especially on a file, class, or method level are useful for either generating documentation (see things like Javadoc or Doxygen as an example) or when using an IDE, where they can be processed and displayed as a tooltip (either when hoving over a method call or in autocompletion to describe the proposed method).

Answer 3

That's a PHPDoc comment. It's useful for both humans and PHPDoc parsers to read, because taking doc comments from various source files and compiling them all into a central HTML documentation site is helpful for a lot of programmers, including myself.

Also, while it makes it a pain to scroll through source files (I'd wager at least 1/4 of some source files are doc comments), it's still nice to be able to check at a glance what a function or method does, while reading its code.

Speaking of which, modern IDEs support doc comments in their IntelliSenses, so they can parse those too and while you're typing out a function, class or method name you'll be able to see right away what it does. There's not even a need to refer to the documentation site in this case.

Answer 4

The comments are very useful. I find online API very useful because it gives me a brief summary on any method and any property I need. The API is generated by a script that uses the comment blocks for that. F. ex. it is much easier to read about loadDataSource() you mentioned from API than from the source if the only thin you need is to find out what it does without specifics.