mathew <[EMAIL PROTECTED]> writes: > On Apr 16, 2006, at 10:52 , Piers Cawley wrote: >> mathew <[EMAIL PROTECTED]> writes: >>> Documentation is as essential to good software as tests. >> >> Bollocks. I'd take good tests over good documentation any day of the >> week. > > Well you're wrong, and we've just had a clear example of why you're > wrong discussed on the list.
Well, up to a point. Yes, our public APIs could do with being better documented (and as you'll notice from another thread on this list, I'm working on making the whole theming API a good deal more understandable/explainable than it is now and I've just written[1] the beginnings of some documentation of the upcoming new style sidebar API), but that doesn't make your original observation anything but a non sequitur. Give me a codebase with good tests and lousy documentation and I can write the documentation reasonably quickly. Give me a codebase with apparently excellent documentation and no tests and I will have very little confidence that it does what the docs say. Which is why I'm far more insistent about tests than I am about docs. > No amount of unit tests was ever going to tell people that > render_component was deprecated, and that render_sidebar should be > used instead. Hence, people used render_component to render sidebars > in all those fancy competition themes, and they all broke. I don't think the render_component version was even deprecated at the time of the competition. It should have been, because forcing theme designers to drop in boilerplate structural code like that is just asking for trouble. I only broke it relatively recently because I've been rejigging the sidebar structure to make it slightly less detestable[2]. I'm pretty sure that I mentioned that render_sidebar was the preferred way when I added it, both here and in the change log. > End result: poor typo reliability. > > Documentation is as essential as unit tests when you have APIs being > used by people who aren't the developers of the API. Anyone who > doesn't see that is a hack. Because calling your interlocutor a hack is *always* going to convince him you're right. 1. http://www.bofh.org.uk/articles/2006/04/16/write-your-own-typo-sidebar 2. detestable: incabable of being automatically tested -- Piers Cawley <[EMAIL PROTECTED]> http://www.bofh.org.uk/ _______________________________________________ Typo-list mailing list [email protected] http://rubyforge.org/mailman/listinfo/typo-list
