Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

designbygravity.wordpress.com

Post reply on HN
Print view View original

31–40 of 60 posts

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

#31

Post by ivenkys »

pgbovine wrote: post #2

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

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.

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

#32

Post by pmjordan »

pgbovine wrote: post #2

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

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.

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

#33

Post by silentbicycle »

olliesaunders wrote: post #19

Michael Feathers' Working Effectively with Legacy Code is the authority on this, I think.

Not quite - it's primarily focused on safely retrofitting unit testing onto legacy codebases, since restructuring code to make it testable can easily break it.

His definition of legacy code is code that doesn't have tests, so you can't fix it or replace units of it without unknowingly introducing bugs.

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

#34

Post by tetha »

known wrote: post #25

One productive technique to read other people's code is to step into the code using a debugger (e.g. gdb)

I disagree with this. The debugger is a very, very precise tool and it can be used to gain very, very precise insights into certain code, however, very often the debugger is just too precise. It is pretty much like trying to understand a large chip by looking at how gates flip and flop.

Of course, if the code is horrible enough, then you might need to switch down to actually tracing line by line and opcode by opcode, potentially even using a debugger, but for most sane code, I think it is possible and faster to understand larger blobs of code at once.

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

#35

Post by tetha »

dbshapco wrote: post #29
dasil003 wrote: post #15

Earlier quoted context omitted.

Now that you know how comments can fail, you should use that knowledge to write good comments rather than not writing any. There are plenty of very good reasons to write comments. The most common reason I write comments is to explain the purpose of something that is unintuitive from the pure code. Examples are comments in CSS about a particular browser quirk, or hacking around an edge case in an efficient but opaque…

. . . and one of the plenty of good reasons being producing API documentation automatically via javadoc, doxygen, etc. Having the API documentation source and code live together is a big win. It's easier to maintain the inline documentation so it doesn't go stale. I hate being forced to go read code when I just want to use an API (I'm looking at you, Dojo :-/ ). One of the first things I'll do encountering a feral co…

What is the point form?

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

#36

Post by [deleted] »

diN0bot wrote: post #9
pgbovine wrote: post #2

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

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…

[deleted]

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

#37

Post by cgs »

Mongoose wrote: post #6

Read the comments, but don’t believe them Love that one. A grad student friend I work with, whenever he catches me poring over documentation, always tells me to read the code. Such a seemingly simple tip, but so valuable.

As my boss likes to say, the extension for Ruby documentation is ".rb".

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

#38

Post by stavrianos »

pgbovine wrote: post #2

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

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.

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

#39

Post by gfodor »

Aschwin wrote: post #8

One of the reasons I don't write comments is because it gets outdated so quickly. And I don't need them myself, because I read only the code, even my own. Reading the code makes also for reviewing the code. Quickly changing bits so it makes better sense (like counts outside the for-loop instead of in the statement) etc. And use version-control system to make changes, test them and roll it back (revert). TortoiseSVN h…

Comments are a hack. There should be a way to include structured documentation with code that lies somewhere between free-form text (comments) and actual code. This documentation should sit at the abstraction level high enough to provide insight not captured in the code directly, but low enough that it actually has some coupling with the implementation so that if the implementation changes the documentation will be broken.

Of course, as long as we are using ASCII text for editing code, this is impossible. A few people are working on fixing this flaw (Intentional Software, Jetbrains MPS) but don't hold your breath!

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

#40

Post by JoeAltmaier »

bmj wrote: post #28
Aschwin wrote: post #8

One of the reasons I don't write comments is because it gets outdated so quickly. And I don't need them myself, because I read only the code, even my own. Reading the code makes also for reviewing the code. Quickly changing bits so it makes better sense (like counts outside the for-loop instead of in the statement) etc. And use version-control system to make changes, test them and roll it back (revert). TortoiseSVN h…

I'm having trouble wrapping my head around this--it seems to boil down to "I don't use comments because then I'd have to actually maintain them." I certainly don't think that every line of code should be commented, but as others have pointed out, some comments are important, particularly around why, say, an algorithm was implemented. Even for my own code, I need these little reminders, especially when I'm jumping bet…

Well said. Comments come in classes, with different purposes. Somewhere (at the top of the module?) its helpful to mention the external dependencies - meta-information that will NOT be found anywhere in the code. For each code unit (method/function/template) explain why it exists, deficiencies, use case. Again, information not immediately obvious by reading code. Finally, those strange lines of code with magic numbers, obscure syntax, checks for apparent side-effects need some illumination. Lastly, and leastly, describing the code itself. These are the comments that get old fastest.
Post reply on HN