Comments vs docstrings

[martinosorb]

This is meant to fix #464 but I'd love some feedback on how to succinctly describe the difference in use between comments and docstrings.

[github-actions]

Thank you!

Thank you for your pull request 😃

🤖 This automated message can help you check the rendered files in your submission for clarity. If you have any questions, please feel free to open an issue in {sandpaper}.

If you have files that automatically render output (e.g. R Markdown), then you should check for the following:

• 🎯 correct output
• 🖼️ correct figures
• ❓ new warnings
• ‼️ new errors

Rendered Changes

🔍 Inspect the changes: https://github.com/swcarpentry/python-novice-gapminder/compare/md-outputs..md-outputs-PR-656

The following changes were observed in the rendered markdown documents:

 18-style.md | 8 ++++++++
 md5sum.txt  | 2 +-
 2 files changed, 9 insertions(+), 1 deletion(-)

What does this mean?

If you have source files that require output and figures to be generated (e.g. R Markdown), then it is important to make sure the generated figures and output are reproducible.

This output provides a way for you to inspect the output in a diff-friendly manner so that it's easy to see the changes that occur due to new software versions or randomisation.

⏱️ Updated at 2023-07-29 00:59:09 +0000

[alee]

A solid start! How about

Use comments to describe and help others understand potentially unintuitive sections or individual lines of code.

Use docstrings to document the expected inputs and outputs of a method or class, its purpose, and/or assumptions and contracts it is expected to uphold. Docstrings are displayed when a user invokes the builtin `help` method on your method or class.

[martinosorb]

Ok, I followed your suggestion with a minor addition:

Use comments to describe and help others understand potentially unintuitive
sections or individual lines of code. They are especially useful to whoever may
need to edit your code in the future, including yourself.

Use docstrings to document the expected inputs and outputs of a method or class,
its purpose, assumptions and intended behavior. Docstrings are displayed
when a user invokes the builtin `help` method on your method or class.

[alee]

LGTM, thanks @martinosorb !