File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
The moose likes Jython/Python and the fly likes Good style for comments in python code? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login

Win a copy of Java Interview Guide this week in the Jobs Discussion forum!
JavaRanch » Java Forums » Languages » Jython/Python
Bookmark "Good style for comments in python code?" Watch "Good style for comments in python code?" New topic

Good style for comments in python code?

Pat Farrell

Joined: Aug 11, 2007
Posts: 4659

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

Joined: Jan 28, 2003
Posts: 4181

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

Joined: Aug 11, 2007
Posts: 4659

Thanks, that helps a little.

Sad to hear no javadocs equivalent in python.

I've noticed that the official, e.g.

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

Joined: Mar 01, 2009
Posts: 2296

You can view the doc strings for modules, classes and built-ins using the help() command e.g. help('os'), help('datetime'), help('') 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.

No more Blub for me, thank you, Vicar.
Steve Fahlbusch

Joined: Sep 18, 2000
Posts: 602

and there is pydoc which is like javadoc
I agree. Here's the link:
subject: Good style for comments in python code?
It's not a secret anymore!