[typo] jabber_notify.rb error

Piers Cawley pdcawley at bofh.org.uk
Sun Apr 16 13:33:21 EDT 2006


mathew <meta at pobox.com> writes:

> On Apr 16, 2006, at 10:52 , Piers Cawley wrote:
>> mathew <meta at pobox.com> 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 <pdcawley at bofh.org.uk>
http://www.bofh.org.uk/


More information about the Typo-list mailing list