I've decided to really revise the documentations of my code today, mainly due to the fact that there hardly is any ;). Also when I haven't had the time for awhile to look into this little project of mine, I didn't have a clue what kinda things I sometimes did and why.
So then I figured, if I want to do it, I may as well do it according to the official guidelines. Said it and whipped out those badboy PEP 257 - Docstring Conventions. Apart from being pretty vague, they are actually quite good </sarcasm>.
I have to be honest, though, doing them at first was as boring as writing can get. Very repetitive and uninspiring, but then I noticed something. An 'A-Ha'-effect if you wish. I noticed an error in my code. A minor one due to sloppiness, but nonetheless an error and I would have not caught it, if it wasn't for writing those bloody docstrings! Then I noticed potential problems in my code or inconsistencies, simply because I went back over it again, because I wanted to document my code.
What I want to say is that these darned docstrings aren't just useful for other people, but for me, too1 It already saved me some hassle, that would have bitten me in the a** about two weeks down the line. I like it, it allows for preventing minor flaws and helps me seeing potential errors and exceptions, which I can then prevent by putting in appropriate fail saves.
In conclusion, I have to say, docstrings are honking useful!
No comments:
Post a Comment