--bKyqfOwhbdpXa4YI
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On Sun, Feb 15, 2009 at 01:34:42AM +0900, David Masover wrote:
> 
> I would turn that on its head. PHP has decent docs, I'll grant, but rdoc 
> isn't completely bad. And when something isn't documented, in Ruby, the 
> source is readable enough that I can usually find out what's going on -- 
> in PHP, it might not be so easy.

I have to agree with that.


> 
> Docs are nice, especially for newbies, but if the language sucks, the 
> language sucks, and no amount of documentation will save it. On the 
> other hand, if the language rocks, docs are a nice bonus, but a lot of 
> it should be self-documenting anyway.

While I disagree with a lot of what 7stud says, I do believe that good
documentation is rather more important than you make it sound.
Sometimes, I don't want to *have* to read the source in order to use the
library -- or, in some cases, the application.  That's especially true
when newbies come along, but also important at times for those who aren't
so new to the language.

Self-documenting code is great for cutting down on the necessary amount
of in-code comments.  It should be viewed as a supplement to -- and not a
replacement for -- out-of-code documentation, though.

-- 
Chad Perrin [ content licensed OWL: http://owl.apotheon.org ]
Quoth Sean Reifschneider: "If java had real garbage-collection, it would
delete most programs before it executed them."

--bKyqfOwhbdpXa4YI
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.10 (FreeBSD)

iEYEARECAAYFAkmXeP0ACgkQ9mn/Pj01uKV+NACdEKF/x9YAaTvF1IyNxVFOvFx2
bAUAmgImVvrXl+2VZxa5A/QkYKiNE7Hc
DY
-----END PGP SIGNATURE-----

--bKyqfOwhbdpXa4YI--