How to Read Other People's Code -- And Why

Re:How to Read Other People's Code -- And Why by pgbovine on Friday October 23, 2009 @01:23AM (#898309)

one technique i often use when trying to understand someone else's code is to add in comments myself in my private branch (of the form "I think that X works like Y and Z"), or even better, adding in run-time asserts that I think ought to hold, and then running tests to make sure they do hold.

Of course, i never check in my comments/asserts to the main branch, since i'm not sure whether my understanding is correct

[ Parent | on HN ]

Re:How to Read Other People's Code -- And Why by pmjordan on Friday October 23, 2009 @08:11AM (#898596)

Of course, i never check in my comments/asserts to the main branch, since i'm not sure whether my understanding is correct

I also add my own comments when understanding/using/changing other people's code. I do eventually check them in though. After all, why not?

* If the original author is no longer available, you're now the best authority on the subject; chances are your comments will help anyone in your shoes sometime later, including yourself. If you're really unsure, add that information to the comments.

* If you're making changes based on your understanding of the code, you or someone else will be testing those changes, thereby validating or falsifying those assumptions. If, after testing, the bugfix/feature/task works, so do the comments.

* If the original author will be available at a future date, you can get them to do a "comment review" (cf code review) when they get back.

[ Parent | on HN ]

Re:How to Read Other People's Code -- And Why by ivenkys on Friday October 23, 2009 @08:09AM (#898594)

I do exactly the same. Added to this, in large legacy code bases with no or very little tests, i sometimes try and break the functionality near to the part where a new fix is required in my private branch to check my understanding. I find that its much easier to understand the code when something doesn't work rather than when its working perfectly. With any luck, the stacktrace will tell me what's going on.

[ Parent | on HN ]

Re:How to Read Other People's Code -- And Why by JoeAltmaier on Friday October 23, 2009 @09:50AM (#898726)

Code management tools need a way to add notations without getting in the way of code. Something that can be view thru a link, but is out of the way when poring over the code. ASCII text: anachronism. We're not that far from 80-column IBM punched cards...

[ Parent | on HN ]

Re:How to Read Other People's Code -- And Why by omouse on Friday October 23, 2009 @10:44AM (#898828)

You want something like literate programming then

[ Parent | on HN ]

Re:How to Read Other People's Code -- And Why by diN0bot on Friday October 23, 2009 @02:57AM (#898393)

if the original code writers had used comments and asserts to not only assert their assumptions but then maintain those assumptions over time, then you wouldn't have to. plus, they'll probably introduce less bugs and debug faster in the future.

i can only speak from my own experience, thought processes and developing skillset. everyone's different. some people can keep track of numerous complex relationships in their head for months on end.

[ Parent | on HN ]

Re:How to Read Other People's Code -- And Why by abstractwater on Friday October 23, 2009 @03:15PM (#899436)

once you determine your understanding is correct (there are a number of ways to make sure of it, like asking the author when he becomes available), I think you provide a service if you abridge your comments and check them in. Sometimes it's like fixing a "incomprehensible code" bug.

[ Parent | on HN ]

Re:How to Read Other People's Code -- And Why by stavrianos on Friday October 23, 2009 @09:31AM (#898695)

if it's unclear enough what the code does that you need to do this, maybe some speculative commenting in the main branch actually would be an improving.

[ Parent | on HN ]