• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Good style for comments in python code?

 
Pat Farrell
Rancher
Posts: 4678
7
Linux Mac OS X VI Editor
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 4181
22
IntelliJ IDE Java Python
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Rancher
Posts: 4678
7
Linux Mac OS X VI Editor
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 2407
33
Linux Oracle Postgres Database Python Scala
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Bartender
Posts: 605
7
Mac OS X Python
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
and there is pydoc which is like javadoc
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic