Thanks for your reply to this topic, John.
I probably should have not brought up 1.2 at all, as it throws my comments into a special case of a "development" release, and we all expect "less" from a development release. In any event my nit is less about The Manual that it is with lack of comments in the code itself. My suggestions apply for 1.x code as well. I spent several days going over some 1.x code a while back, and there was not a stitch of helpful comments in there anywhere. One nice example of commenting is inside the core.php file, which describes all the options, some noteworthy side effects, and so on. In other words, it gives insight, which is what we all want and need. I am not dissing anyone for their efforts on Cake because of lack of good commenting and documentation, but I am saying that it ultimately makes the product less valuable to people who want to use it.. and that's too bad considering the effort that has gone into it. I would love to help out with the commenting of the code, but I must first become an expert at parts of the system on my own because the current code does nothing to get you up to speed with what you are looking at :-) Might I ask you some questions at some point, about the system? Michael On Jan 5, 12:06 pm, "John David Anderson (_psychic_)" <[EMAIL PROTECTED]> wrote:
On Jan 5, 2007, at 9:27 AM, Veloz wrote: > 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.The first developer release for 1.2 was released on Christmas. I imagine I could have done a better job preemptively documenting new things in 1.2, but don't be too hard on me for not documenting features that aren't even final yet. Its hard enough for me to document exist final features. I don't think we'll try to nail down something that is still a moving target, thus the "development" label on the release. <snip> > 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.I don't think this is always practical, and in some cases, development releases allow us to see how things work in the wild. Seeing the community response helps us know when to modify things, either because of bugs or requested features or whatever. I agree with you, however, if this is referring to final releases (as all our releases are stable :). > 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".Again, this just isn't practical for development releases, due to the nature of them not being a final release. It's kinda like writing a review on a broadway play's dress rehearsal. As with many other open source and free efforts, its always better to volunteer to fix the solution rather than just point out where things need to improve. A negative budget and many other priorities often make it hard to decide where to best place our efforts. We totally agree with what you're saying here, but your point would have more impact on the community if you jumped in and made an effort to contribute and fix the problem. Anyone is welcome to supply some documentation to the code blocks - please just log a ticket at trac.cakephp.org and attach a few lines you think might clarify the situation. Having everyone help out makes fixing these issues much faster for us - especially if you've already spent the time figuring a section of code out. Thanks, -- John CakePHP Docs
--~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
