in reply to RFC - Linux::TCPServer (new module)

I also think I like Net::TCPServer::Linux best. Regarding the documentation, I hesitate to say it (because it's great to see someone take the time to actually provide extensive documentation), but it's a bit much ;-). A lot of the information given in the .pod is on the internals of the modules, design decisions and general networking background. IMO the module documentation should be there foremost to describe the user interface, things that are important to the user of the module. I'm not saying that any of the information you give is useless, but perhaps some of it could be broken out into a separate document (or separate sections in the docs). As it is, valuable user information is mixed together with design decisions and it's a lot to read for someone who is not familiar with the module. YMMV.

The example in the pod also seems a bit long and would IMO be better in a separate script in an example/ subdirectory. Examples in the pod should be general-purpose and preferably only show how the module itself works (and not include external database connections and the like). Again, YMMV, and I'll be interested to read what others think of this.


Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it. -- Brian W. Kernighan

Replies are listed 'Best First'.
Re^2: RFC - Linux::TCPServer (new module)
by ph713 (Pilgrim) on Oct 30, 2005 at 09:43 UTC

    Yeah you're probably right about all of that. The module was written out of personal need, so I guess I've always been coming at it as a user, and thinking in terms of how to best write code that uses the module when I'm writing the documentation. I think I will still keep most of the extraneous detailed stuff in another pod somewhere though. Basically, if your project *really* needs this module, chances are high you're going to want to know all of that stuff if you don't already (the network stuff that is).

    Actually, it's not worth making a seperate pod just to rehash socket-related manpages, curious users can figure that out for themselves

    The implementation details probably don't matter so much, I may just move them over to comments in the C code.

    I think I'll just kill the example in the docs and tell people to read the lib/Net/TCPServer/Linux.pm source for the example. It's basically the same thing minus the database stuff, and it's the default callback implementation that gets used by the test script, etc.

    ETA: That exact BWK quote has been in the back of my mind for the past couple of weeks, because I know I've been too clever for my own good in numerous places in the C source of this module. :)
[reply]

In Section Meditations