Following an interesting discussion on Sitepointforums, a rough poll.
If you’re getting started with some class library, like one of the many in PEAR, which of the following (if any) steps do you take to work out how to use it (and in what order)?
a: Examples package with the code
b: API docs (such as that generated by phpDocumentor or the PHP manual)
c: Reading the source code
d: Any packaged documentation (such as tests and READMEs)
e: Guessing method names (with IDE help) and parameters.
f: Online tutorial (e.g. those on Sitepoint or a developers WIKI)
g: Pair programming
h: Print magazine articles
i: Book chapters
I think it was Einstein who said, “Examples aren’t just a good way to teach; they’re the *only* way to teach.”
Examples are the easiest way for me to learn a library. They should be very simple examples, with as little outside code as possible. Of course, examples coupled with tutorials are all the better.
I can usually learn easily enough from API docs, but the problem is, they serve better as references than as guides. A reference lists all the calls and classes, while a guide lists possible uses and explains what calls and classes to use.
February 25th, 2004 at 11:46 am
f., a., c., b., usually in that order. I usually will look at the source code if I need to use the library in a way that isn’t explicitly in the examples and then look for confirmation in the API docs.
February 25th, 2004 at 11:58 am
“f” then “a”, then “d”, then “b”, then I either give up or do a little “c” before giving up.
February 25th, 2004 at 2:29 pm
Well… All of the above, depends on how sophisticated the class is. I learned how to use the PEAR’s Date class be reading the source code. DB class had a nice documentation with examples, so I chose that. First steps when I was learning Smarty were reading through the quick start with examples in manual… So it is not always the same.
February 25th, 2004 at 3:40 pm
In no particular order: a, b, d, f, and i (thanks to your books).
I’d have to say I read source code of a class ONLY when I’m curious about how it achieves it’s results, or I wish to extend it. API Docs are great, but as Chris noted, make handier references than learning tools. Again, agreeing with Chris, examples usually lead to the highest clarity in the shortest amount of time.
g: Pair programming
Pardon my ignorance, but what’s this?
February 25th, 2004 at 8:25 pm
Yeah, I always learn by example, then quite often, a nice read through the souce to see where and why things work.
After that if there’s good supplied documentation I’ll give it a quick browse (who reads the manual anyway ;) hehe).
February 25th, 2004 at 8:43 pm
In order:
c: Reading the source code
b: API docs (such as that generated by phpDocumentor or the PHP manual)
a: Examples package with the code
e: Guessing method names (with IDE help) and parameters.
d: Any packaged documentation (such as tests and READMEs)
f: Online tutorial (e.g. those on Sitepoint or a developers WIKI)
i: Book chapters
h: Print magazine articles
g: Pair programming
February 25th, 2004 at 8:47 pm
f: Online tutorial (e.g. those on Sitepoint or a developers WIKI)
a: Examples package with the code
c: Reading the source code
b: API docs
so keep on your good work on Sitepoint :o)
February 26th, 2004 at 7:30 am
a, f, b, d
I’d agree with Chris that examples are the easiest way for me to learn as well, followed closely by the tutorial with…good examples.
February 26th, 2004 at 2:36 pm
First: a, d, b
Always give me a good impression see some explanation of the racionality of the class or library. Next, i look for a complete example and the api doc. Last, if I don’t understand something, i see the source code.
February 26th, 2004 at 6:10 pm
Some interesting results – keep em coming.
As PHPDeveloper points out, would be good, some time, to turn this into a proper survey.
[QUOTE=beetle]
g: Pair programming
Pardon my ignorance, but what’s this?
[/QUOTE]
Pair programming is a doctrine from Extreme Programming. In crude terms it means two programmers sit in front of one computer. One does the programming and the other watches, providing verbal input.
The idea (as I understand it – ) is to encourage discussion of design and reduce the number of bugs / errors at the point a “first draft” of code is done, rather than as seperate stages in the development process (which may or may not actually take place).
You really want to ask Marcus about it, who’s actively pair programming in his software development company.
Extreme programming also advocates unit testing, BTW.
February 27th, 2004 at 6:16 am
I always look for an online tutorial when I want to learn something new. So for me, it would be f,a,b,c.
February 27th, 2004 at 7:15 am
Hi…
g, e, d (tests), f|h|i, c, a|b|d (docs). It was shame you did not divide up “d”.
btw: A more informative eXtreme Programing link is http://www.extremeprogramming.org/
yours, Marcus
March 6th, 2004 at 11:48 am
I wish I could read the “End User” documentation for PEAR packages.
But I have been burnt with this approach many times because it turns out the documentation is missing key information is or is frankly inaccurate.
So I have to read through the source code for myself and decipher what’s going on and sort of guess at how the original author meant for the class or classes to be used.
The worst documentation is where the funtion name and parameters are described but not in enough detail. Bad documentation fails to describe the datastructures which a function is supposed to accept. And bad documentation doesn’t explain how the function uses the data structure to achieve the purpose of the function, this means you don’t know what parts of the data structure you can change and what you can’t.
It is too risky to trust the documentation on PEAR because over time I have found the documentation doesn’t match the actual operation. The problem with this is that it makes it difficult to know what your doing wrong if the program isn’t working as expected.
The packages I use mainly are DB, DB_Table, Date, Mail, Mail_Queue, Validate, Auth, QuickForm, QuickForm_Controller and that’s about all I can think of right now.
This sounds like a rant and it is. I had hoped that PEAR would save me some time and headaches but it made projects more risky because the documentation was insufficient. Instead of being able to just plug in and go, I had to experiment with the code. Instead of simply learning how and when to use it and then making it happen, I did what I thought was correct according to what I could make out from the documenation, but to get unexpected results.
The point of all this ranting is that yes, now my behaviour has changed, I prefer to check the source code. BUT, if the documentation was better, I’d much prefer using that to learn the packages. Good documentation describes the data structures, the purpose of all the elements, the intended usage of functions, the intended collaboration between classes, and so on. PEAR needs more and better documentation!
December 18th, 2005 at 8:46 am
To answer the original question I refer to the following sources in order from first to last.
d: Any packaged documentation (such as tests and READMEs)
b: API docs (such as that generated by phpDocumentor or the PHP manual)
a: Examples packaged with the code
c: Reading the source code
I avoid secondary sources as much as possible out of fear of inaccuracies which could lead to programming errors. Source code is the most reliable and is the only “truth”. Examples packaged with the code can be out-of-date. Auto-generated API docs are usually pretty good. Packaged documentation can be out of sync with the source code and examples. So if I get any problems at all from the documentation, I try the next most reliable source and eventually the source code.
December 21st, 2005 at 12:26 pm