I am a relative new-comer to Cake and am impressed and appreciative of the quality of effort that has gone into the project so far.
However, I have found that many of my questions are not answered in "The Manual" nor in Tutorials/FAQ's, nor in the Google Group, etc. Ths is especially true for changes that are part of the newest releases. So I have turned to the code to get the "answers". What I have found is that the code is nice and clean, all pretty and with well named variables, etc, so kudos to the team for that. But to my disappointment the code is effectively undocumented too, leaving me in a bad position: I either have to tell my boss that I made a mistake and Cake is not the tool for us, or I have to spend more days trying to figure out someone else's code and add this to my project timeline. My newest case in point is the FormHelper class, which presumably one needs (as of release 1.2xxx) to emit form input tags. Yes there are headers that say things like "$options is an optional array of options" and "the input function creates an input tag". Are these kinds of comments helpful? Not really. If we users of Cake are going to have to rely on the code to figure things out ourselves (which is somewhat expected when using Open Source) then I would suggest that the coders might be kind enough to help by interjecting some useful comments inside the code to help those who don't already know the framework and its ins and outs. When I write code I am careful to comment each function while coding it. Often times I write in sections of comments before I even write the code. This is similar to how Agile programmers write test code before writing the actual code. I look at each function as a series of steps that must be taken in order to achieve the end result of the function. Then, for each of these steps I try to include a comment that gives some insight to that step: what the step is supposed to achieve, and how I expect that the following lines of code are going to achieve it. I try to point out exceptional cases, make mention of key design concepts, list input and output options clearly, and make mention of things I didn't do that you might normally expect, and my reason for doing so. This way, one can read the comments and get inside my mind and understand what I am expecting the code to do. This helps in several ways: 1. It helps people understand what the function can and cannot do without having to take the function apart line by line. In other words, it provides useful documentation. Not just for the users but for the author too. 2. It helps find bugs. If I have a comment that says something like "next we need to multiply the width of the widget by the height of the gadget" yet the following code shows me asking the widget for its weight, not it's width, then you know something is wrong. 3. If the function needs to be rewritten or modified, you have a sense of context, scope, purpose, constraints, etc, related to the current function. So, my suggestions for improving the state of documentation for Cake is: 1. Do not release any version of Cake unless The Manual has been updated to reflect the changes in that release. 2. Make sure all functions are commented before allowing the code to go into a release. This should be part of your "conventions", not just a "nice to have". Thanks, Michael --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Cake PHP" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/cake-php?hl=en -~----------~----~----~----~------~----~------~--~---
