Re: New Package: HTML_DB

On Fri, 25 Apr 2003, Richard Heyes wrote: > > May I ask where > > a poor, hapless developer, up against the wall, is supposed to work out how > > to write a log message using your class? Oh, there it is - in the source > > code. > > Well yeah! The Log package has great docs in the source, as do many packages. doxygen comments do not good documentation make. Especially if said comments do not exist except in the source code. > And do try to remember, you are *developers* - PHP source code isn't hard to > read, even for beginners. So why bother writing docs at all, then, if it's all in the source? > > Many paragraphs were expended proving you know "software engineering > > design patterns", but you couldn't put 3 lines somewhere saying "you send a > > message to the log with the log($msg, $prio) method" and some talk of what > > messages and priorities actually are. > > Umm, surely you jest? Nope. Although there was levity in there, the core of the comment is made in total seriousness. I like to avoid reading the code unless I suspect a bug. Yes, I can read the code quite easily, but it takes time to do so. I read a lot about how PEAR is trying to become CPAN for PHP, and how it's going to dominate the world, etc. I'm trying to poke a few developers into making that happen, because it sure as hell isn't going to happen when the entire documentation for a class doesn't mention how to do the *main* *thing* *the* *class* *exists* *for*. -- ----------------------------------------------------------------------- #include <disclaimer.h> Matthew Palmer, Geek In Residence http://ieee.uow.edu.au/~mjp16