I'm not going to name the module because I don't want to slam the author, but I'm reinventing a CPAN wheel. My boss, in looking at some of my code, knew the module that I was ignoring and asked me why.
"Because I can't understand the documentation."
The module actually looks like it would be useful, but try as I might, the docs may as well be written in Klingon. I suspect that the module actually does far more than I need as the interface in some of the examples is very complicated, so I could use the "leaner, meaner version" argument. But I still can't understand the docs. If you're going to write a CPAN module, don't skimp on the documentation. If I can't understand it, I probably won't use it.
My vote for bad module of the day is Ananke::Template which is just a bad imitation of TT.
Re:be brave!
merlyn on 2002-10-28T21:10:57
But that's not the only bad imitation of TT. Look at HTML::KTemplate as well. Like most of the worst of TT mixed with HTML::Template. Ick.Re:be brave!
gav on 2002-10-28T21:24:28
Ick. The only thing worse than inventing the wheel is doing it badly.I may have to start scouring the depths of CPAN for a "bad module of the week". This may help the Schwartz factor a bit
:) Re:be brave!
koschei on 2002-10-29T00:28:52
It would probably be nice to give the authors a chance
to clean up their module before announcing their shame.
Otherwise you'll just become loathed =)
Re:be brave!
jdporter on 2002-11-11T20:43:45
Along these lines, I nominate Text::Macros. It has documentation more or less sufficient for what it does, but what it does is crummy. I think the author released it (four versions!) without ever bothering to finish it.Re:be brave!
Ovid on 2002-10-28T23:31:01
No can do. The module itself appears to be useful and some checking around reveals that others are using it (though not very widely). If it was a bad module, I don't mind calling a spade a spade. I just want to be sure that I'm being decent and not trashing a good module just because someone didn't do a good job of communicating. Let's face it, programmers who write great code are often known for being less than diligent about their docs
:) Amusingly, I found a tutorial for using this module that was even worse. I went back, read the docs again and am even more convinced than ever that this module is overkill for our needs, so I don't feel too bad about rewriting it (it only took me about 3 hours).
Re:be brave!
mary.poppins on 2002-11-01T03:26:41
I don't feel too bad about rewriting it (it only took me about 3 hours)
Yeah, the great thing about Perl is how easy it is to write stuff. I think that is an important reason for the success of CPAN -- it is easy to add stuff, because it's easy to write in the first place! Syntax *is* important (take that, lisp fans)!
Re:be brave!
lem on 2002-11-08T02:31:53
Is this, by any chance, NetAddr::IP?Not being a native english speaker, and having a tutorial online at The Perl Monastery, it would not surprise me.
If it is indeed one of my modules, I would want to know.
Regards.
-lem
Re:be brave!
Ovid on 2002-11-08T03:39:40
No worries. It's an entirely different module.
Re:be brave!
nattis on 2003-12-15T12:43:50
Hi,
Yeah, is one imitation of TT, but, Ananke::Template use only 200k of memory and TT use 2M, imagine 100 modperl using with persistent connection... Anake::Template is very very very speedy and small.
Now i have other module, NTS::Template (Ananke::Template rewrite), is more stable, speedy and use less memory... but documentation is bad
my english is bad;)
bye
Re:Writing docs
pudge on 2002-10-30T19:15:13
I am not the very model of a modern extreme programmer, but I try to document the API was I go, and that is most of the battle right there. I should probably write tests too, but, well, I, um, have to go eat dinner...
