in reply to OOPerl isn't that bad after all...

I used to worry about this sort of thing all the time. Really it would keep me awake at night. Then I ditched Windows, and switched to Unix. Fairly soon I stopped worrying. I'm not trying to start an OS holy war here - hell, I've no idea about what your favourite Desktop OS is (but I'm guessing Windows). But there is definately some sort of culture thing going on which I only became aware of when I switched.

With windows I suppose it can be best summed up as "maintain control" - and is the responsibility of the creator of the code. Whereas with Unix it's more like "best practice" - and is the responsibility of the user of the code.

I'm a fan of "best practice". It seems like it's less work when I'm hacking code. I also like the possibility of stepping outside the envelope if I wish - although I've learned that's usually not a good idea. But the main reason is that I don't need to write decent API documentation... read the code POD if you really want to know.

--
TTFN, FNORD

xaphod

Replies are listed 'Best First'.
Re^2: OOPerl isn't that bad after all... (do write docs)
by Aristotle (Chancellor) on Oct 05, 2003 at 20:10 UTC

    The source being available is no reason not to write documentation. If everyone had to read the glibc and Linux kernel sources to write programs for Linux, we'd never have gotten anywhere.

    Documentation is like sex — when it's good, it's very good, and when it's bad, it's still better than nothing.

    The fact that POD makes it particularly easy to document means you really have no excuse not to write documentation. Imagine CPAN without POD, and half the modules without documentation: sure, there's all this great code out there, but if you want to know what it does you have to download and unpack it, and if there's no docs, read the source. How much use would such a repository be?

    One thing that's cool about the hacker culture, however, is that even if you only wrote very sparse docs to begin with, if there's a lot of interest in your code it's likely that others will contribute documentation. They can also spot documentation errors for you, because they can read the source. Just remember that without any docs, it's not likely that anyone else will get interested. Make it habit to slap at least some basic POD onto your Perl code.

    Makeshifts last the longest.

[reply]

      The source being available is no reason not to write documentation. - True. Doesn't stop me from being lazy.

      The fact that POD makes it particularly easy to document... - I'd forgotten about POD, it's so much part of my perl, it is perl.

      I should also add that even if you don't plan to release your code, writing some documentation is "best practice", it will save hours of irrtation when you need to hack some of your old code.

      --
      TTFN, FNORD

      xaphod
[reply]

In Section Meditations