On Sat, Nov 16, 2013 at 12:49 AM, Jean-Michel Pichavant <jeanmic...@sequans.com> wrote: > If the documentation is sparse, writing the doc yourself is one way to dive > into someone else's code. To begin with, you can stick to the function > purpose, and for the WTF functions try to document the parameters and return > values as well.
Agreed. I just had someone do that with my code - it was sparsely commented, and he went through adding docs based on what he thought functions did (based on their names and a cursory look at their bodies - return values, particularly, were often documented by description, which wasn't particularly useful with certain callbacks). Seeing where he'd misdescribed something was a great way for me to figure out which functions were poorly named, or at least begging for better comments. If you have the luxury of working with the original programmer, that would be something I'd strongly recommend. Even if you can't, try to set some comments down; but be aware that false comments are worse than none at all, so do notate which are your comments and which bits you're particularly unsure of. ChrisA -- https://mail.python.org/mailman/listinfo/python-list
