5 ms·

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 lik

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

JoeAltmaier 17y ago
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...
- omouse 17y ago
  You want something like literate programming then
diN0bot 17y ago
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.
- deleted 17y ago
  [deleted]
ivenkys 17y ago
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.
pmjordan 17y ago
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.
stavrianos 17y ago
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.
abstractwater 17y ago
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.

JoeAltmaier 17y ago

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...

omouse 17y ago
You want something like literate programming then

diN0bot 17y ago

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.

deleted 17y ago
[deleted]

ivenkys 17y ago

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.

pmjordan 17y ago

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.

stavrianos 17y ago

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.

abstractwater 17y ago

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.