[Tutor] A tip from someone who is clawing his way out of being a
Brian van den Broek
bvande at po-box.mcgill.ca
Mon Jun 7 02:01:01 EDT 2004
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
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,
More information about the Tutor