I've always followed the guideline that the code tells you what it does, the comments are added to explain why it does something.
If you can't read the code, you have no business looking at it, so having (in the extreme):
index += 1 # move to next item
is a total waste of time. So is a comment on a function called calculate_inverse(matrix) which states that it calculates the inverse of the matrix.
Whereas something like:
# Use Pythagoras theorem to find hypotenuse length.
hypo = sqrt (side1 * side1 + side2 * side2)
might be more suitable since it adds the information on where the equation came from, in case you need to investigate it further.
Comments should really be reserved for added information, such as the algorithm you use for calculating the inverse. In this case, since your algorithm is simply handing off the work to scipy, it's totally unnecessary.
If you must have a docstring here for auto-generated documentation, I certainly wouldn't be going beyond the one-liner variant for this very simple case:
"""Return the inverse of a matrix"""
Hello, all!
I've been working on my docstrings skills and I've ran into the problem of how to write a docstring for my main method. I couldn't find much with my google fu, so I'm thinking that this might fall to an opinion question.
So, if my driver script (named prog.py) looks like
#! python
""" prog.py """
def main():
"""
Main method.
Main method ran when executing the prog.py file from console.
This method is not designed to be called like a method from a module.
Parameters
-------------
None
Returns
---------
None
Raises
-------
None
Examples
-----------
????????????
"""
pass
if __name__ == '__main__':
main()If I never intend to allow my main method to be imported and ran like a module method, do you have any suggestions on how to write the examples section of the docstring?
Do you feel that a docstring is not needed for the main method()?
Thank you so much in advance for your opinions and advice!
EDIT: Formatting and engrish.
docstring - Should you always document functions, even if redundant (specifically python)? - Stack Overflow
Advice on writing some docstrings
Propper way to write DocStrings
Do short functions need docstrings?
Videos
I've always followed the guideline that the code tells you what it does, the comments are added to explain why it does something.
If you can't read the code, you have no business looking at it, so having (in the extreme):
index += 1 # move to next item
is a total waste of time. So is a comment on a function called calculate_inverse(matrix) which states that it calculates the inverse of the matrix.
Whereas something like:
# Use Pythagoras theorem to find hypotenuse length.
hypo = sqrt (side1 * side1 + side2 * side2)
might be more suitable since it adds the information on where the equation came from, in case you need to investigate it further.
Comments should really be reserved for added information, such as the algorithm you use for calculating the inverse. In this case, since your algorithm is simply handing off the work to scipy, it's totally unnecessary.
If you must have a docstring here for auto-generated documentation, I certainly wouldn't be going beyond the one-liner variant for this very simple case:
"""Return the inverse of a matrix"""
"Always"? Definitively not. Comment as little as possible. Comments lie. They always lie, and if they don't, then they will be lying tomorrow. The same applies to many docs.
The only times (imo) that you should be writing comments/documentation for your code is when you are shipping a library to clients/customers or if you're in an open source project. In these cases you should also have a rigorous standard so there is never any ambiguity what should and should not be documented, and how.
In these cases you also need to have an established workflow regarding who is responsible for updating the docs, since they will get out of sync with the code all the time.
So in summary, never ever comment/document if you can help it. If you have to (because of shipping libs/doing open source), do it Properly(tm).