Good style for comments in python code?

[Pat Farrell]

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.?

[Steve Luke]

There is a PEP describing it: PEP 257 Docstring conventions

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.

[Pat Farrell]

Thanks, that helps a little.

Sad to hear no javadocs equivalent in python.

I've noticed that the official, e.g.
http://docs.python.org/2/library/stdtypes.html#file-objects

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.

[chris webster]

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.

[Steve Fahlbusch]

and there is pydoc which is like javadoc