Live data from Hacker News

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

designbygravity.wordpress.com

51–60 of 60 posts

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

#51
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 aren't for you. They're for whomever comes along later and needs to understand what you did. (Well it could be you, just several months in the future).

Sure, someone could read all the code, but it's way faster to just skim and pick out the comments if you don't care about the details. Think of code commenting as a time-saving device.

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

#52
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…

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…

One of the best reasons to write comments is that the comment describes what the author wants the code to do. What he wanted was not necessarily what he coded - bugs do creep in, after all.

If you confine yourself to reading code, but no other comments or documentation, you may think the code's behavior is correct, even though it's buggy.

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

#53
post #45

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…

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

In this specific case, the dashboard-page function is actually sequencing operations, not performing them (except for 5, and I'd wonder why that couldn't be moved to a separate function), and can be described as such:

  // - control the login sequence
  function login_sequence() {
    var user  = verify_login
    if (!user) {
       user = login();
    }
    var providers = collect_providers(user);
    var profiles = collect_profiles(user);
    var account_info = collect_account_info(user);
    load_templates(user);
    display_templates(providers, profiles, account_info);
  }
(Forgive the guess at what your code might look like.)

State may be passed between called functions, and used in control decisions, but state should not be grossly manipulated in sequencing functions (I do find with this style of programming that at high levels the state passed around tends to be large 'context' objects, rather than granular arguments encountered at lower levels). What I would NOT want to see in such a hypothetical login function is ALL the actual lower level code to do the login, collect the data, etc., so that essential higher order detail is obscured by the lower level operations.

A function's API comments do not need to repeat the purpose of called functions.

As I come up with API comments last, I usually think about them in reverse -- it's not 'I need to think of the single purpose of this function before writing it', but 'what single purpose did this function end up serving?'. Not being able to think of a decent answer for the latter is a possible symptom of sub-optimal decomposition. Then again, cutting blocks of code and pasting them into their own functions has become an instinct rather than conscious decision for me, so I'm effectively anticipating writing the 'single purpose' API comments.

At a certain level of detail I don't need to know the minutae of login, just that there is some black box function that controls the lower level details. And if I need to know the details, I break open the function and follow its call flow (or look at the autogenerated call graph in the doxygen docs or similar).

Having read a lot of feral code, I find the major indicator of quality is the static navigability of the code base (i.e. can I find my way around just by reading the code in an editor, without resorting to debuggers or autogenerated documentation), and having a level of detail structure, akin to the zoom feature on Google maps, is one method of achieving navigability (and partially the value of OO techniques). So it's okay to have functions/methods that simply sequence or aggregate calls to lower levels, and to describe them as such.

It was mentioned elsewhere on the thread that debuggers are useful tools in understanding a code base -- and I do often find myself setting breakpoints on code because it's near impossible to understand how particular functions get invoked by just reading the code. Then examining the call stack at the breakpoint I see that event loop called the network code invoked some code to read a database, which called into some code to instantiate widgets, which called back into the database code, which called the code that calculates order totals and tax, which called the widget code again to update those fields, all of which goes 30+ levels deep.

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

#54
post #48
post #35

Earlier quoted context omitted.

What is the point form?

Perhaps in bullet points?

An example from my code:

  /// - parse an HTTP input stream as XML
  ///   - requires a progressive parser (currently xpat, which is distributed with
  ///   Apache)
  ///   - the XML in turn is mapped to database operations, and the results
  ///   of the database operations used to create the HTTP response

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

#55
post #34
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,…

Not to mention the side effects of breaking code you don't understand at random points.

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

#56
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…

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…

The question I always ask before writing a comment is: will it contain the word "because?" If so, there is probably a need for a comment. If not, I will try hard to make the code more readable before breaking down and adding the comment.

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

#58
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

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.

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

#59
post #34
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,…

YMMV. But that's how I understood Apache's Httpd code http://httpd.apache.org/dev/debugging.html

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

#60
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.…

That'd be the day :D Drawings for comments is absolutely a great idea. Sometimes I wish I could "draw" something in my code (Arrows, bookmarks, quick diagrams, etc. beside comments). Think github with this kind of feature.
Post reply on HN