I've taken over some python code for a project that I'm working on. Its nearly 100% comment free. I'm used to how we use javadoc within Java code.
I can't find any explanations and examples of best practice commenting styles for python.
I've seen a couple of guides that contain the usual, be positive, no passive voice, etc. But does one normally document the parameters passed into a method? Since python is auto-typed, does one document the expected argument types passed? etc.?
The short answer is you should document the variables, default values, etc...
For auto-documentation tools, there is no 'javadoc' equivalent in the built-in python, so there are a number of tools which fill the gap. Unfortunately they all have their own syntax. I think the most popular is Sphinx: Also mentioned in Python docs page.
doesn't specify the return type. If you read the description prose carefully, you can sometimes pick up hints. I'm finding it more than a little frustrating to find what the built-in or library functions actually do, or what they expect as parameters.
You can view the doc strings for modules, classes and built-ins using the help() command e.g. help('os'), help('datetime'), help('datetime.date') or help('dict'). There are also various third-party libraries for generating documentation from the doc strings e.g. Epydoc although I haven't used any of these so I've no idea if they're any good.
Of course, doesn't help much if there's no doc strings to begin with.
0
