Style, readability and docstrings

[Charles Cazabon]

Timothy Grant claimed in <38B5BDA9.4B12EC57 at exceptionalminds.com>:

>I posted a little code sample the other day and got a couple of comments
>back on my "python style". One of those comments suggested that I move
>my function comment headers blocks into docstrings.
>
>I have done so, and now I can barely read my code, I don't know what it
>is about those comment blocks at the top of a function that my eyes
>like, but without my function header comment blocks, my eyes don't
>immediately pick up each function as I scroll through my code.
>
>Is this a "You need to retrain your eyes" type thing? Have other's
>noticed the same thing, and does anyone have a nice coding style that
>works for them that I can borrow?

Sure.  I put the comments in the doc string, so they're available to users, 
automated doc extracters, etc.  But, like you, I find the comment delimiter 
helps my eye find the start/end of functions/methods.  That and the fact 
that my editor can colourize the comments easily enough.

So I use contentless comments to mark the function starts:

#!/usr/bin/python

import qux, quux, quuux

# Globals
PI = 3.14159
FILE = 'output.txt'


##############################
def main ():
    	'''Program to do foo.'''
    	a = foo ()
    	b = bar (a)


##############################
def foo ():
    	'''Doc string here.'''
    	blah
    	blah
    	return baz


##############################
def baz ():
    	'''Doc string here.'''
    	blah
    	blah
    	return qux


##############################
if __name__ == '__main__':
    	main ()




Works for me.

Charles