How to Read Other People's Code -- And Why • Hacker News Board

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

#41

Post by JoeAltmaier » Fri, Oct 23, 2009, 1:47 PM UTC

wenbert wrote: post #16

Maybe it's just me. But sometimes I draw diagrams describing how the code will work and how the methods interact with each other. A quick drawing with a pencil and paper or on a whiteboard will do. It helps me understand how the over-all system works...

Agreed. If it won't all fit in my head at first, put some of it on paper. Especially when learning the code. And re-visit the drawing, testing it against what I'm reading as I go until I'm sure its right. Once its in my head, throw it away. Wish there was some way to use drawings as comments... My friend Bob learns differently - he needs words, skips all the illustrations in manuals, they just don't sink in for him. He's brilliant, just built differently.

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

#42

Post by JoeAltmaier » Fri, Oct 23, 2009, 1:50 PM UTC

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

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

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

#43

Post by tetha » Fri, Oct 23, 2009, 2:26 PM UTC

olliesaunders wrote: post #17

bendtheblock wrote: post #14

Earlier quoted context omitted.

When I was studying CS, one of the things I was told was that if you grep and get only the comments out of a particular file/class, you should effectively see the pseudo-code of the program. In reality, I comment very little, just pointing things out that can’t be quickly deduced from casually reading the code.

I hope you don't still believe that's a good idea! That's a recipe for out-of-date documentation. Even if the comments are up-to-date they'll only be saying things that can be inferred from the code itself, less precisely.

I have to state that I have seen a case where keeping comments around which formed pseudo-code was a good idea, even though it was just once, and it was a very nonstandard case.

Basically, the comments were text and relational algebra in LaTeX which explained the implementation of dataflow equations by using sets and those relational algebra expressions were then implemented in operations on binary decision diagrams. However, as I said: this does not occur often. In fact, one might call it rare ;)

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

#44

Post by omouse » Fri, Oct 23, 2009, 2:44 PM UTC

JoeAltmaier wrote: post #42

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

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

You want something like literate programming then

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

#45

Post by dstorrs » Fri, Oct 23, 2009, 3:11 PM UTC

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…

>In writing my own code, I decompose until each function or method has a single purpose (f() does X, not X & Y & Z!),

I hear this one a lot, from a lot of different sources. In practice, it never seems that practical. Here's a trivial example: the dashboard-page function in our webapp. It needs to do all of the following:

1) verify that the user is logged in. If not, bounce them to the login page, then bring them back on successful login

2) collect the list of all their providers

3) collect the list of all their profiles

4) collect the list of all their account information

5) load up and display the appropriate templates to render the web page with the requisite information.

Now, points 1-4 are accomplished by calling other functions, true. But dashboard-page still needs to do 5 separate things.

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

#46

Post by jcl » Fri, Oct 23, 2009, 3:29 PM UTC

alexkearns wrote: post #22

I don't know about the rest of you but I got into software development to create software (ideally from scratch) and to learn clever new stuff, not to tinker with someone else's code. Of course, just like every other software developer, I have on occasions ended up working in someone else's codebase. But I have done this not out of choice - and except in a handful of cases, I have not gained any knowledge or mental s…

At some point in your career, you come to realize that unreadable code is bad code -- and that if you aren't writing readable code, you are a bad coder. Usually this realization comes when you are asked to fix something in code so horrible that it causes you to wonder aloud, "What idiot wrote this?" And you look in the repository logs and see that it was you, several months ago.

Even if you never intend to maintain code, if you don't want to be that guy whose code everyone hates to work on -- whether out of compassion for your maintainers or out of career self-interest -- you need to know how readable your code is relative to others'. And the only way to know this is to read other people's code.

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

#47

Post by eru » Fri, Oct 23, 2009, 4:15 PM UTC

cgs wrote: post #37

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

The extension for Haskell-documention is `.lhs'. But you can compile it to a `.ps' or `.pdf' with LaTeX if you want to.

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

#48

Post by eru » Fri, Oct 23, 2009, 4:18 PM UTC

tetha wrote: post #35

dbshapco wrote: post #29

Earlier quoted context omitted.

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

Perhaps in bullet points?

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

#49

Post by bendotc » Fri, Oct 23, 2009, 4:32 PM UTC

tetha wrote: post #34

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,…

Agreed.

In general, if you're having trouble tracing through a particular function with a narrow band of input, then the debugger can be useful. If you're trying to figure out a larger system and/or how a system works across a large set of inputs, then stepping through with a debugger is useless.

Put another way, the debugger is to programming what the microscope is to medicine: incredibly useful for some things, but not a very good general diagnostic tool. Metrics data and checking assumptions (via unittest and/or asserting expectations based on reading the code) are much better for getting an over-all idea of what's going on. Once you've localized a problem, then the debugger can help you get a precise idea of the issue, or can help you test a hypothesis (to use the medical example, you can use the microscope to test a theory that there's a bacterial infection).

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

#50

Post by bmj » Fri, Oct 23, 2009, 5:01 PM UTC

JoeAltmaier wrote: post #40

bmj wrote: post #28

Earlier quoted context omitted.

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 number…

I would add one more class of comments that would sit at the bottom of the hierarchy: TODOs. When I'm sketching out functions, I typically outline what should be done with within the context of the function, then fill in the implementation details later. This often leads to stuff like this:

  // Replace with a link to the core
  AddStartupShortcut("Shell.lnk", Path.Combine(INSTALL_PATH, "foo.exe"));

  // Update device time:
  _log.Information("Updating device time...");
  SetDeviceTime();

I always intend on cleaning these up, but often never do.