[Tutor] A tip from someone who is clawing his way out of being a Python newbie

[Brian van den Broek]

Hi all,

I've struggled along and reached the point with Python where I can code 
some serious fun ;-) projects. I recently discovered something I'd like to 
share with other relative newcomers:

         Write docstrings. Write them early and often.

I don't know that all/many more experienced Pythoners would agree, and I 
know that many talented programmers dislike writing documentation. But I 
have found that the effort I put in to writing a semi-English docstring 
for my functions seems to have been more than repaid in the time saved 
tracking down bugs.

I've tried both writing the docstring before the function, and just after 
I think I have a first version. I'm not yet sure which is more effective, 
but both have saved me from a good deal of pain caused by not coding what 
I meant. The effort of rendering an explanation for existing or projected 
code has really saved me from my own sloppy thinking a few times. 
Likewise, revising a docstring to account for changes made to code has 
often exposed that the change wasn't what I thought I'd made.

I've actually come to think that at least for me, writing docstrings is at 
least as useful as running tests -- too often I miss the test case that 
would expose the bug, but in explaining my code I seem more likely to 
catch it.

Of course, docstrings are good practice anyway, and they really do speed 
up the process of understanding code you wrote weeks before. So, I'd been 
putting them in everything, but until recently only once I had a finished 
program. Doing them earlier has improved my programming more than anything 
else in the last while.

Anyway, I thought I'd throw that out there for what it is worth.

Best to all,

Brian vdB