Interpreting others' source code

Question

Note: I am aware of this question. This question is a bit more specific and in-depth, however, focusing on reading the actual code rather than debugging it or asking the author.

As a student in an introductory-level computer science class, my friends occasionally ask me to help them with their assignments. Programming is something I'm very proud of, so I'm always happy to oblige. However, I usually have difficulty interpreting their source code.

Sometimes this is due to a strange or inconsistent style, sometimes it's due to strange design requirements specified in the assignment, and sometimes it's just due to my stupidity. In any case, I end up looking like an idiot staring at the screen for several minutes saying "Uh..."

I usually check for the common errors first - missing semicolons or parentheses, using commas instead of extractor operators, etc.

The trouble comes when that fails. I often can't step through with a debugger because it's a syntax error, and I often can't ask the author because he/she him/herself doesn't understand the design decisions.

How do you typically read the source code of others? Do you read through the code from top-down, or do you follow each function as it's called? How do you know when to say "It's time to refactor?"

I would say: do not waste your time on bad programmers, even while in college ... unless you charge them for it. The trick to success is: take their $ while making em look stupid. — Job, Mar 07 '11 at 15:11
@Job: Well, we all wrote bad code when we were starting out. Whether they're worth spending time on depends on whether they care to work on their own and improve. — , Mar 07 '11 at 15:53
@Job I'm in high school and I want to treat my friends properly. While I can see the logic behind treating it as a competition, I'm trying to be a nicer person. — Maxpm, Mar 07 '11 at 16:41
And this way you actually eliminate competition while being nice to them. If you solve everything for them, you'll learn a lot and they'll be helpless. (On the flipside, they'll get a degree, which combined with their lack of knowledge means they'll probably go into management straight away. :)) — biziclop, Mar 08 '11 at 11:20

score 22 · Accepted Answer · answered Mar 07 '11 at 13:31

22

First tip: use an IDE (or a very good editor :)) to spot syntax errors, misplaced parentheses and other trivial mistakes.

Second step: Autoformat all code in a format you feel comfortable with. You'd think this doesn't matter much but amazingly, it does.

Don't be afraid to rename local variables if they are poorly named. (If you have access to the full system, you can rename anything and you should.)

Add comments to yourself when you discover what a certain function/method is doing.

Be patient. Understanding alien code isn't easy but there's always a breakthrough moment when most pieces of the jigsaw suddenly fall into place. Until that point it's all hard work and drudgery I'm afraid. The good news is that with practice this eureka moment will come sooner.

answered Mar 07 '11 at 13:31

biziclop

3,351
21
22

How can I reformat/rename while still respecting the original author? Should I leave comments saying stuff like `// Renamed to ABC for XYZ`? – Maxpm Mar 07 '11 at 13:44
3

@Maxpm The straightforward answer is that you don't have to respect the original author. Code is not a work of art, and if it isn't working, it definitely isn't. But you can put comments like that in, so it's easier to explain to the original author what you changed and why. The why is very important, wherever possible, document why you're doing things. It's the most useful type of comment. – biziclop Mar 07 '11 at 13:47
6

@Maxpm - you copy the code file. Do what ever you want to it and then go back and help them fix the problem on there system. Well that is how I would do it. – Erin Mar 07 '11 at 13:48
@Maxpm Make a copy of the code and run it through astyle (http://astyle.sourceforge.net/) first. People learning how to program rarely have consistent coding styles. Seeing the code properly formatted helps a lot when visually "parsing" it. – Vitor Py Mar 07 '11 at 14:04
1

@Maxpm, copying and working on your system is the best but even if you have to do it in front of them (like if they ask you to come over and help you) if you need to rename a variable just tell them that you didn't write it, so don't know what everything is doing so you need to rename to it figure out. – Dominique McDonnell Mar 07 '11 at 21:11

score 20 · Answer 2 · answered Mar 07 '11 at 13:57

20

May I say that I think you are taking the wrong approach with this. If folks are turning to you for help with their code, I think you have the responsibility to turn around and say to them to walk you through their code. You can fix their errors for them, and they may learn something (by rote), if they can spot their own errors (with your help) they are likely to learn more. Additionally, you will gain wider experience with how different people approach coding (which will in turn allow you to read/understand more code) - a virtuous cycle... ;)

answered Mar 07 '11 at 13:57

Nim

1,363
1
11
17

2

why the down vote? this seems like a good idea. – Matt Ellen Mar 07 '11 at 14:39
I agree. Seems very odd. – Michael K Mar 07 '11 at 14:54
@Matt ad Michael, drive-by-downvoters, not much you can do I guess... – Nim Mar 07 '11 at 14:55
A nice idea but in real life you're more likely to be given a code "that bloke from support who was fired for watching porn at work wrote eight years ago" and then what, there's nobody to run to. Plus what is the real value of an explanation given by someone who probably struggles with the basics? – biziclop Mar 07 '11 at 15:57
This is a good answer. They should have some idea of what they think their code is suppose to do or at least want it to do. – JeffO Mar 07 '11 at 16:02
+1 - This is what I do with all the junior developers. 9 times out of 10 they find their own problem while explaining it too me. It doesn't work as well with senior developers. Maybe because the problems they run into are usually more complex. – Dunk Mar 07 '11 at 21:18
@biziclop: I agree with your observation about how it works in 'real life', but Maxpm specifically stated that this was beginner programmers working on high-school level programs. If Maxpm continues to use the method described by @Nim, the knowledge and familiarity will come with practice. – oosterwal Mar 08 '11 at 18:59
@oosterwal Fair enough. I only looked at it from the perspective of getting the job done. But if you consider it as helping your peers learn, communication is definitely the way to go. – biziclop Mar 08 '11 at 20:02

score 3 · Answer 3 · answered Mar 07 '11 at 13:52

I believe this ability is a mix of experience and just having a talent for it. We've had employees that could solve more or less anything if we asked them to make something from scratch, while at the same time being completely unable to find obvious bugs in pieces of code they didn't write. And, simultaneously, we've had employees that we wouldn't trust with anything exceeding basic design, but who could dive into others code and track down issues in no time.

That said, the way to approach this is to change the code. Reformat it to what you're used to, change variable names to something that makes sense to you, add comments if the code isn't clear. If he asked you for help, you should just go ahead and change things until you spot the problem. Then leave it up to your friend whether to correct the original code or use yours.

+1 - Developing code and tracking down bugs written by other people are 2 very different skillsets. Employers don't appreciate what they have when they find someone that can do both very well. — Dunk, Mar 07 '11 at 21:21

score 2 · Answer 4 · answered Mar 07 '11 at 14:15

First, if there are syntax errors, you simply have to read the compiler errors carefully. Often a line is highlighted as an error, but it was actually the previous line that has the error.

Be aware that, for an introductory student, there may be some editing artifacts that will prevent the program from being compiled that cannot be seen. For example, I once saw a student (not one of mine) who used the spacebar instead of return: His code looked normal on an editor that wrapped after 80 columns (the student was very patient), and the code even worked until he added a "//"-style comment, which commented out all of the rest of the program. Similarly, if you copy code samples from a website, there are often unprintable characters that are copied too (depending on how the website formatted the code). When in doubt, re-type in a line without copy and paste. [It's kind of amazing, but I've seen it happen a lot more lately.]

For nasty compiler errors, you may have to grow the program, by creating a new file and typing in all of the code as you go along. Make sure to compile after each major step before moving on to the next one.

OK, so what about if there are no syntax errors? Then it's time to step through the code! You can use a debugger for this, but putting in calls to printf throughout the code is also highly effective. For example, if there's a for loop, add in a print statement for the loop counter. In the case of nested for loops, you may find that the wrong variable is being incremented.

The advantage of using printfs is its ability to "compress" over time/space what you're currently looking at. When you step through with a debugger, you also see a lot of irrelevant state and it can be more tedious. Also, without seeing a history of what has been printed to the console, you might miss some patterns. The point here is that the debugger and printfs are complementary techniques, and neither is always better than the other.

Finally, simply ask your friend what's going on! Instead of looking at it and saying "uh" ask them what they are doing: "now what does n do?" By starting the dialog, they may end up answering their own question, or, you may realize the way they conceptualized the program had a flaw, which can lead you to a solution.

As commented elsewhere, all of this gets better with experience. Even though I've been programming for 20 years, it wasn't until the past 5 years I've been working with students that I've gotten better at helping them with their errors.

score 1 · Answer 5 · answered Mar 07 '11 at 13:53

I hate to say this, but there's no silver bullet here.

Frankly if I was clairvoyant enough to be able to understand what others meant when they wrote what they did even in 10% of the cases, I would without a shade of doubt made millions by now.

On a more practical note, using an intelligent IDE is step 1.

Step 2 would be to run doxygen or something similar to figure out the source code hierarchy.

Step 3 is to find out anchor functions or objects, stuff that processes your command line or file and then performs logic.

In parallel to Step 3, keep track of globals if you are using them. Also ask your mates if they are using any known specific algorithm -- reading the algorithm (if there exists one) before looking at the code is always beneficial.

score 1 · Answer 6 · answered Mar 07 '11 at 14:04

In one word: Experience, the more you gain experience, the more you learn of best practices and can judge/understand other people's code. It doesn't come automatically, instead it often only comes from doing the same mistake yourself!

That said, it is essential that programmers learn to comment their code properly because when you look at code it often is just the result of a major thought process that often is very difficult to extrapolate from the code. A few comments, a text file with design thoughts can make the difference between understanding the code and completely misunderstanding it.

score 1 · Answer 7 · answered Mar 07 '11 at 14:54

I was often asked the same in the lab in school. Usually the question started with, "How do I fix this compiler error?" so I got pretty good at spotting dangling else's, missing semicolons and the like. (Macros are fun to debug too - #define CUBE(x) x * x * x is a mistake we all are destined to make.) An advantage I had was that I had gone through the same classes with the same teachers, so I was already familiar with the requirements.

The process I found to work best is to keep a running dialog. You don't want to write the program for them, since they're the one that needs to learn. This means you have to be at the same computer with them. In the lab I would come to their computer. I would try to get them to spot the error, by starting with the compiler message. (We were using C.) Start with the line number, and point out where the message and the error correspond. If there is more than one of the same error, I would ask them what was similiar about the two errors.

The whole idea is to help guide the other student. Rewriting their code for them will not help them learn.

what is wrong with `#define CUBE(x) x * x * x` other than type-unsafety? — Job, Mar 07 '11 at 15:18
When called like `CUBE(3)`, it's fine. Call it with `CUBE(x + 1)` and you get `x + 1 * x + 1 * x + 1` which in C is evaluated `x + (1 * x) + (1 * x) + 1`. This evaluates to `3x + 1` which is not x³! You fix it by declaring `#define CUBE(x) (x) * (x) * (x)`. — Michael K, Mar 07 '11 at 15:35

score 0 · Answer 8 · answered Mar 08 '11 at 05:27

Syntax errors are a whole lot easier to find than logic errors. If most of their problems are syntax, find an IDE, copy and paste their code into it, and fix the errors. Logic errors are much more difficult. I'm not sure why you say you cannot ask them to explain their code. I've found many a logic error by explaining code to someone else.

Interpreting others' source code

8 Answers8