It appears your teacher is a fan of How to Design Programs ;)
I'd tackle this as writing for two different audiences who won't always overlap.
First there are the docstrings; these are for people who are going to be using your code without needing or wanting to know how it works. Docstrings can be turned into actual documentation. Consider the official Python documentation - What's available in each library and how to use it, no implementation details (Unless they directly relate to use)
Secondly there are in-code comments; these are to explain what is going on to people (generally you!) who want to extend the code. These will not normally be turned into documentation as they are really about the code itself rather than usage. Now there are about as many opinions on what makes for good comments (or lack thereof) as there are programmers. My personal rules of thumb for adding comments are to explain:
- Parts of the code that are necessarily complex. (Optimisation comes to mind)
- Workarounds for code you don't have control over, that may otherwise appear illogical
- I'll admit to TODOs as well, though I try to keep that to a minimum
- Where I've made a choice of a simpler algorithm where a better performing (but more complex) option can go if performance in that section later becomes critical
Since you're coding in an academic setting, and it sounds like your lecturer is going for verbose, I'd say just roll with it. Use code comments to explain how you are doing what you say you are doing in the design recipe.
Answer from dejester on Stack OverflowIt appears your teacher is a fan of How to Design Programs ;)
I'd tackle this as writing for two different audiences who won't always overlap.
First there are the docstrings; these are for people who are going to be using your code without needing or wanting to know how it works. Docstrings can be turned into actual documentation. Consider the official Python documentation - What's available in each library and how to use it, no implementation details (Unless they directly relate to use)
Secondly there are in-code comments; these are to explain what is going on to people (generally you!) who want to extend the code. These will not normally be turned into documentation as they are really about the code itself rather than usage. Now there are about as many opinions on what makes for good comments (or lack thereof) as there are programmers. My personal rules of thumb for adding comments are to explain:
- Parts of the code that are necessarily complex. (Optimisation comes to mind)
- Workarounds for code you don't have control over, that may otherwise appear illogical
- I'll admit to TODOs as well, though I try to keep that to a minimum
- Where I've made a choice of a simpler algorithm where a better performing (but more complex) option can go if performance in that section later becomes critical
Since you're coding in an academic setting, and it sounds like your lecturer is going for verbose, I'd say just roll with it. Use code comments to explain how you are doing what you say you are doing in the design recipe.
I believe that it's worth to mention what PEP8 says, I mean, the pure concept.
Docstrings
Conventions for writing good documentation strings (a.k.a. "docstrings") are immortalized in PEP 257.
Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the def line.
PEP 257 describes good docstring conventions. Note that most importantly, the """ that ends a multiline docstring should be on a line by itself, e.g.:
"""Return a foobang Optional plotz says to frobnicate the bizbaz first. """For one liner docstrings, please keep the closing """ on the same line.
Comments
Block comments
Generally apply to some (or all) code that follows them, and are indented to the same level as that code. Each line of a block comment starts with a # and a single space (unless it is indented text inside the comment).
Paragraphs inside a block comment are separated by a line containing a single #.
Inline Comments
Use inline comments sparingly.
An inline comment is a comment on the same line as a statement. Inline comments should be separated by at least two spaces from the statement. They should start with a # and a single space.
Inline comments are unnecessary and in fact distracting if they state the obvious.
Don't do this:
x = x + 1 # Increment x
But sometimes, this is useful:
x = x + 1 # Compensate for border
Reference
- https://www.python.org/dev/peps/pep-0008/#documentation-strings
- https://www.python.org/dev/peps/pep-0008/#inline-comments
- https://www.python.org/dev/peps/pep-0008/#block-comments
- https://www.python.org/dev/peps/pep-0257/
PEP 8 -- Style Guide for Python Code categories comments and document strings (a.k.a. docstrings) under comments sections.
Comments
- Block Comments
- Inline Comments
- Documentation Strings
Block comments generally apply to some (or all) code that follows them and are indented to the same level as that code.
Inline comments are unnecessary and in fact distracting if they state the obvious.
A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition.
Now to answer your question
Docstrings are for people who are going to be using your code without needing or wanting to know how it works. Docstrings can be turned into actual documentation. Consider the official Python documentation - What's available in each library and how to use it, no implementation details (Unless they directly relate to use).
In-code comments are to explain what is going on to people those who want to extend the code. These will not normally be turned into the documentation as they are really about the code itself rather than usage. Now there are about as many opinions on what makes for good comments (or lack thereof) as there are programmers. My personal (credits) rules of thumb for adding comments are to explain:
- Parts of the code that are necessarily complex. (Optimisation comes to mind).
- Workarounds for the code you don't have control over, that may otherwise appear illogical.
- I'll admit to TODOs as well, though I try to keep that to a minimum.
- Where I've made a choice of a simpler algorithm where a better performing (but more complex) option can go if performance in that section later becomes critical.
Code comments and docstrings have different purposes and audiences:
Developers write docstrings to describe the function's behaviour. Other developers, who use this function, read docstrings to find about the meaning of parameters, the pre- and post-conditions, possible exceptions etc.
If you're writing an API, you may want to publish docstrings as a part of documentation, but have your code and code comments private.
Developers write comments to describe the code's inner logic, when this logic isn't clear from just reading the code. The audience is themselves and other developers, who will modify this function in the future.
confused about the differences. I know a comment doesn't affect the code but explains it. But does a doc string affect it? why not just make a comment? I'm talking about python