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

Re: Coming up with good examples in POD

by stevieb (Canon)
on Jul 25, 2020 at 19:51 UTC ( [id://11119801]=note: print w/replies, xml ) Need Help??


in reply to Coming up with good examples in POD

I usually snag chunks of my test files to use in SYNOPSIS and EXAMPLES sections.

That, or take some test parts and slightly modify them for such a purpose. Your unit test suite should have every imaginable (to you) angled use of your software, and tests should be written before, or as you write code, so A) you know it works, B) it should be literally copy/pasteable and C) so long as the test code never changes, your examples shouldn't have to either.

  • Comment on Re: Coming up with good examples in POD

Replies are listed 'Best First'.
Re^2: Coming up with good examples in POD
by Lady_Aleena (Priest) on Jul 28, 2020 at 05:48 UTC

    The history of this sub is probably I wrote a once off script, that is now gone. I liked the sub so plonked it my my Util::Sort with all my other sorting subs. It is easy enough to figure out how to use, so no usage was written for it anywhere. It has been sitting in my Util::Sort module a long time growing metaphorical moss.

    I have not written any tests for any of my work yet. I am writing all the POD first, then I will get to the tests, eventually. The last time I looked at the Test suite of modules, I got so confused on their usage, that I just quit trying. That was years ago when I was still learning how to write and had severe confidence issues. I still have confidence issues, though not as severe.

    It will be especially hard to write tests for the modules I wrote and do not use.

    My OS is Debian 10 (Buster); my perl versions are 5.28.1 local and 5.16.3 or 5.30.0 on web host depending on the shebang.

    No matter how hysterical I get, my problems are not time sensitive. So, relax, have a cookie, and a very nice day!
    Lady Aleena
      "I have not written any tests for any of my work yet. I am writing all the POD first, then I will get to the tests, eventually. The last time I looked at the Test suite of modules, I got so confused on their usage, that I just quit trying."

      Thing is, if you get all of the POD done, then write tests, what happens if by writing tests you find glaring issues, and you need to modify the public interface? You now have to scour all of your documentation to ensure all examples, usages and explanations get updated as well.

      To be honest, I feel that test cases are the best practice for confidence. You get familiar with the process, but it also allows you to have a closer relationship with your code (as you're usually bouncing back and forth from the test and the code).

      "It will be especially hard to write tests for the modules I wrote and do not use."

      If you don't use them, they are the perfect modules to learn how to write tests against. Nobody else is using them either presumably, so if/when you find glaring bugs and problems, you already know the code isn't in production anywhere. Not so much for writing code for modules already in production.

Log In?
Username:
Password:

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

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

    No recent polls found