Enhance the Tests section with best practices for clarity and documentation

[akhilkrishnar0]

Hi everyone,

I'd like to propose adding a new “Tests” section to the packaging guide that outlines best practices for writing clear, well-documented tests. This idea came up in a recent conversation pyOpenSci/software-peer-review#201, where we discussed the value of making tests easier for reviewers and contributors to understand.

Here’s what the new section could include:

• Use of meaningful test names that reflect what is being tested
• Docstrings or comments in test functions/modules that describe the purpose of the test
• Clear test structure and organisation
• Simple examples of good and bad test documentation practices

This would help both reviewers (who need to understand what’s being tested) and new contributors (who may want to add tests or debug).
Thanks to @ucodery for suggesting that I open this issue to get the conversation started.
Any comments or contributions are invited.

[akhilkrishnar0]

I found that tests are already covered in this issue: #59 (comment)

I'm realising now that the current "Tests" section already does a solid job of covering the basics. As a beginner, I don’t feel I can meaningfully contribute more at this stage, so I’ll step back and leave this issue open in case someone with more experience wants to build on it. I'm happy to revisit this in the future as I gain more insight.