File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
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
JavaRanch » Java Forums » Languages » Jython/Python
Bookmark "Good style for comments in python code?" Watch "Good style for comments in python code?" New topic
Author

Good style for comments in python code?

Pat Farrell
Rancher

Joined: Aug 11, 2007
Posts: 4646
    
    5

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
Bartender

Joined: Jan 28, 2003
Posts: 4174
    
  21

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.


Steve
Pat Farrell
Rancher

Joined: Aug 11, 2007
Posts: 4646
    
    5

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
Bartender

Joined: Mar 01, 2009
Posts: 1649
    
  14

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.


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

Joined: Sep 18, 2000
Posts: 559
    
    7

and there is pydoc which is like javadoc
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Good style for comments in python code?