views:

95

answers:

4

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
 */
+3  A: 

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)...

ircmaxell
I agree documentation is good. But comments === documentation is not always true. I am not questioning the docs, only the comments in the code.
cdburgess
I've started using Cake for the first time in the last month. Understanding some of the core functions can be really tough with all the "magic" Cake does, and my unfamiliarity with the codebase. The excellent commenting in the source files has made my life easier multiple times.
MBCook
True, but doc blocks (Method comments) are oven a lot better than inline comments. I never trust inline comments (since there's a good chance the code around the comment changed). But I find it's far more rare that the workings of the method change significantly without the docblock changing (Not saying it doesn't happen). And yes, you're right not all comments are valid enough (or complete enough) to be considered documentation)... But it's only one part in a whole...
ircmaxell
Great point on the inline comments. I think I have officially decided that I will not include those comments inline anymore. Is that a bit premature of me? It does seem like a waste of everyones time as the code changes, to mess with inline comments. I think I will restrict them to the doc block style of comments.
cdburgess
I use inline comments, and recommend that every one does. But use them properly. When you need to write something that "looks funny", or may possibly be difficult to understand (or works around a funky bug), then absolutely toss an inline comment with a quick "why". Don't get into the trap of documenting the "how" inline, since that's what the code is for...
ircmaxell
+4  A: 

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).

Thomas Owens
+7  A: 

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.

BoltClock
I totally forgot about the intellisense on the comments. I use Komodo so I should have remembered. Thanks for bringing this up. I can see where that would be useful.
cdburgess
in addition http://api.cakephp.org has been made from the code comments :)
Nik
A: 

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.

bancer