understanding someone else's program

[Chris Angelico]

On Sat, Nov 16, 2013 at 12:49 AM, Jean-Michel Pichavant
<jeanmichel at 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