Beefy Boxes and Bandwidth Generously Provided by pair Networks
Think about Loose Coupling
 
PerlMonks  

Re^2: [RFC] Review of module code and POD

by Bod (Parson)
on Mar 31, 2021 at 22:11 UTC ( [id://11130643]=note: print w/replies, xml ) Need Help??


in reply to Re: [RFC] Review of module code and POD
in thread [RFC] Review of module code and POD

Thank you

Yes, I did wonder if I was going to start a major debate about POD being inline or clumped at the bottom. I took the view, without thinking about it too much, that it is probably easier to write it next to the subroutines it relates to whilst developing the module. Then, once that subroutine is proven working and shouldn't need touching again, shift its POD to the bottom out of the way. Whether this moving would ever happen of course is up for debate!

For this one I don't need to worry about CPAN rendering but I still want to try and get it right for the future.

Is it worth also trying to write tests for this - again for practice and learning - if so, where would I start?

  • Comment on Re^2: [RFC] Review of module code and POD

Replies are listed 'Best First'.
Re^3: [RFC] Review of module code and POD (TDD)
by eyepopslikeamosquito (Archbishop) on Apr 01, 2021 at 01:09 UTC

    Is it worth also trying to write tests for this - again for practice and learning - if so, where would I start?
    Before you write the module. :)

    The main point of TDD is that writing the tests first (or at least early) affects and improves the design of the module! Writing a test first forces you to focus on interface - from the point of view of the user. Hard to test code is often hard to use. Simpler interfaces are easier to test. Functions that are encapsulated and easy to test are easy to reuse. Components that are easy to mock are usually more flexible/extensible. Testing components in isolation ensures they can be understood in isolation and promotes low coupling/high cohesion. Implementing only what is required to pass your tests helps prevent over-engineering.

    To give a clearer picture of where I'm coming from, a quote from Ten Essential Development Practices:

    The most important aspect of any module is not how it implements the facilities it provides, but the way in which it provides those facilities in the first place. If the module’s API is too awkward, or too complex, or too extensive, or too fragmented, or even just poorly named, developers will avoid using it. They’ll write their own code instead. In that way, a poorly designed module can actually reduce the overall maintainability of a system.

    Designing module interfaces requires both experience and creativity. Perhaps the easiest way to work out how an interface should work is to “play test” it: to write examples of code that will use the module before implementing the module itself. These examples will not be wasted when the design is complete. You can usually recycle them into demos, documentation examples, or the core of a test suite.

    The key, however, is to write that code as if the module were already available, and write it the way you’d most like the module to work.

    Once you have some idea of the interface you want to create, convert your “play tests” into actual tests. Then it’s just a Simple Matter Of Programming to make the module work the way that the code examples and the tests want it to.

    See also: Re: Winning people over to better development practises (TDD) and On Interfaces and APIs

Re^3: [RFC] Review of module code and POD
by perlfan (Vicar) on Mar 31, 2021 at 22:31 UTC
    100%, yes, write tests for your module. It's unclear if you meant for the POD. I am not sure I would go that far. Besides it wouldn't go to improving your test coverage :).

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://11130643]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others lurking in the Monastery: (2)
As of 2024-04-20 09:39 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found