> I am trying to improve my code quality and have started using doc > strings. What format do you guys use for your doc strings ? > I have 'made up' the following general format ... > > def gen_vhost(kmotion_dir): > """ > Generate the kmotion vhost file from vhost_template expanding %directory% > strings to their full paths as defined in kmotion.rc > > arguments : > kmotion_dir ... the 'root' directory of kmotion > > exceptions: > exit ... if kmotion.rc cannot be read > > returns: > """
dave, excellent question and good to see that "you care" enough to ask. docstrings are one of Python's strengths, esp. given some of the external tools that are at your disposal. a) my 1st suggestion is to add some code to any of your docstrings where it makes sense; and even better would be some output. for example: def foo(x): """foo(x): display argument 'x' >>> foo(123) 123 """ print x this is helpful because if you're writing code for others (including yourself), it's easy to see what the proper syntax/usage is. b) given the above, wouldn't it be neat if there was a tool that could actually *execute* that code in your docstring as a regression test to (help) ensure code correctness? well, there is, and it's called the doctest module. if you add in the snippet below, you've just added testing for your code (and docstring)! def _test(): import doctest doctest.testmod() if __name__ == '__main__': _test() when you run your program, it should give no output if things ran swimmingly. if you do get output, that means that something went wrong. to see that it really works, just run your code with a "-v" flag: $ foo.py -v Trying: foo(123) Expecting: 123 ok 3 items had no tests: __main__ __main__.User __main__._test 1 items passed all tests: 1 tests in __main__.foo 1 tests in 4 items. 1 passed and 0 failed. Test passed. ----- the output tells you that of the 4 places that docstrings could go, only 1 had a test in a docstring (the other 3 didn't). c) on top of this, i would also 2nd kent's suggestion of using Epydoc, which is also compatible with doctest docstrings: http://epydoc.sourceforge.net/manual-epytext.html adding a bit more, you get this: def foo(x): """foo(x): display argument 'x' >>> foo(123) 123 @param x: this is the main arg for foo() @type x: 'x' can be any object, i.e., int, str, etc. @return: None since there is no explicit return """ print x now you can use Epydoc to generate HTML or PDF documentation of your entire code base! hope this helps! -- wesley - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - "Core Python Programming", Prentice Hall, (c)2007,2001 http://corepython.com wesley.j.chun :: wescpy-at-gmail.com python training and technical consulting cyberweb.consulting : silicon valley, ca http://cyberwebconsulting.com _______________________________________________ Tutor maillist - Tutor@python.org http://mail.python.org/mailman/listinfo/tutor