Re^2: Coming up with good examples in POD

in reply to Re: Coming up with good examples in POD
in thread Coming up with good examples in POD

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

Comment on Re^2: Coming up with good examples in POD

Replies are listed 'Best First'.
Re^3: Coming up with good examples in POD by stevieb (Canon) on Aug 01, 2020 at 18:49 UTC
"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.	[reply]

Replies are listed 'Best First'.

Re^3: Coming up with good examples in POD
by stevieb (Canon) on Aug 01, 2020 at 18:49 UTC

"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.

[reply]

In Section Seekers of Perl Wisdom