This week's giveaway is in the EJB and other Java EE Technologies forum.
We're giving away four copies of EJB 3 in Action and have Debu Panda, Reza Rahman, Ryan Cuprak, and Michael Remijan on-line!
See this thread for details.
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 EJB 3 in Action this week in the EJB and other Java EE Technologies 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
Author

Good style for comments in python code?

Pat Farrell
Rancher

Joined: Aug 11, 2007
Posts: 4634
    
    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: 3946
    
  17

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: 4634
    
    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: 1476
    
  11

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: 555
    
    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?
 
Similar Threads
I looooove GroovyConsole
usage of "this"
groovy and javafx
Android SDK is a Simulator or Emulator?
SQL error