in reply to Writing TIMTOWDI-friendly CPAN Modules

This may sound rude -- but write the module for yourself. Don't try to second guess how other people are going to want to use it. If you make it, and release it, and other people have suggestions, they'll tell you.

If you make it complicated to the point where you don't even want to use the module, you've done too much work. You know what works for you. Without some sort of focus group, you're not going to know what it is that everyone else wants ... so put out something that helps you, and then see what other people comment on that would help them.

The most important thing to writing modules is writing documentation, which I find to be one of the more difficult parts of the experience. So I would suggest writing the documentation first. (yes, I know, it sounds stupid, but it's actually like writing a use case, or writing test cases first).

You write the documentation in a way that it makes the module easy to use in a program, then write the module to fit that documentation. If you have to, you can also write a cookbook as a series of ways that you expect the program to behave, and then use it as both documentation, and tests

  • Comment on Re: Writing TIMTOWDI-friendly CPAN Modules

Replies are listed 'Best First'.
Re^2: Writing TIMTOWDI-friendly CPAN Modules
by ihb (Deacon) on May 15, 2005 at 19:25 UTC

    if you make it, and release it, and other people have suggestions, they'll tell you.

    Will they really? Or will they write another module? As eyepopslikeamosquito points out you're interface is kind of locked down. If you flag the modules as alpha and the interface many change it's likely people just won't use your module, and you won't get the feedback.

    In my opinion it very well can be better to use various resources to request feedback before you release it.

    If you make it complicated to the point where you don't even want to use the module, you've done too much work.

    Having a worked-out interface and a thought-through approach doesn't mean you have a bloated module. Keep it simple, but also don't paint yourself into a corner.

    ihb

    See perltoc if you don't know which perldoc to read!

[reply]
      In my opinion it very well can be better to use various resources to request feedback before you release it.

      in my opinion, to get useful feedback, you need to actually release something. Specially for modules related to some specific field, say bioinformatics, its much easier to get bioinformatics to comment on your module if you give them some working code.

      If you start with a complete API doc, but without code, then you will get feedback but more of the "teorical" kind... and then you will need to discern the good advice for the bad!, with working code you can just try and decide... thought, obviusly, you should be willing to change things.

      Be realistic, you don't upload a module on CPAN and zillions of people start using it, and anyway, most people will expect a module at version 0.01 to be unstable, and will not complaint about API improvements.

[reply]
      Will they really? Or will they write another module? As eyepopslikeamosquito points out you're interface is kind of locked down. If you flag the modules as alpha and the interface many change it's likely people just won't use your module, and you won't get the feedback

      I never suggested releasing alpha code. I fact, I will never knowingly release code that I'm not comfortable with. I'm required to release code due to requirements for my job (US federal government), but I have held off putting it into CPAN because I'm not happy with the quality of the documentation, or the depth of the installer tests.

      It would take a lot for me to install something that I specifically know is alpha code, and that the API isn't fixed... But I never suggested that anyone do so. I consider 'alpha' code to be anything that is known to not work as intended, known to have issues that may cause interaction problems, or that has undergone no significant testing. In my opinion, alpha should never leave the shop it was developed in. Beta, to me, is when you have passed your internal testing, but pass it out to others to test as well.

      I also have a different situation than many other people, as 'my' work is part of a team effort, so I have three other people that I regularly bounce ideas off of, and we have two other external groups who are actively making use of our API, and it's very difficult for me to keep our alpha seperate from beta. (in system terms, development vs. qa/testing)

      Yes, it is entirely possible that someone may not like your module, and decide that it's better for them to write all new code. That is not a failure on your part. Your first responsibility is to yourself, not to everyone else who might find interest in your module. This may sound rather rude, but we do not live in a purely gift society. You are never going to satisfy every possible potential user.

      This is true in any endevor -- in most situations, you can apply the 20/80 rule -- 20% of the customers require 80% of the effort. If you are writing code for yourself, and you're one of the 20%, Then doing a little bit of work to get everyone else happy isn't a big deal. However, if you go out of your way to satisfy other people, then you're exhibiting signs of co-dependency.

      My job pays me to do my work, not someone else's. Sure, I can throw in a few tweaks here and there for other people, but they don't want to pay me for solving other people's problems. I can do it on my own time, and I frequently do, but I've been trying to cut back, as I know I have every one of the signs of co-dependency, and many of the signs of being a workaholic.

      If the module is useful to you, then there's a possibility that other people may find it useful. If they drop a comment on improvements, you don't have to oblige them -- under most licenses that perl code is released under, they can always fork the project if they want to make changes that you don't want, for whatever reason.

      If you make it complicated to the point where you don't even want to use the module, you've done too much work.
      Having a worked-out interface and a thought-through approach doesn't mean you have a bloated module. Keep it simple, but also don't paint yourself into a corner.

      How did you manage to get from one quote to the other? If you make it complicated to the point where you don't even want to use the module, you've done too much work. If the module is no longer something that you want to use, there's something wrong. It's no longer something that you'll care about, and you're not the person who should be maintaining.

      There might be someone else who would be willing to improve and maintain it, or fork their own, but there is something fundamentally wrong about working on a project that you do not want to use.

      There are valid times for fork a project. Trying to make your program do everything for everyone frequently results it in becoming useless for most people. (Hell, I can't even get people to agree on how to specify time). If you can, make it so that people can inherit the module, and override parts they need to change, but you don't need to do everyone else's work for them.

[reply]

In Section Seekers of Perl Wisdom