Reading Code Is Hard

re: Reading Code Is Hard

Patrick Steele — Mon, 14 Jun 2004 19:29:00 GMT

"Don't write 'clever' code".

Agreed!! We've got a bunch of code laying around with stuff like this:

bComplete = (sState = "complete" ) ? true : false;

Hello? How about simply:

bComplete = (sState = "complete");

re: Reading Code Is Hard

Eric Lippert — Mon, 14 Jun 2004 19:35:00 GMT

I'd classify that as more "redundant" than "clever".

I see that kind of thing all the time, particularly in VB/VBScript. People seem to think that a conditional needs an operator.

If Blah = True Then

instead of

If Blah Then

Of course, these two things have different meanings. The former will execute the consequence only if Blah really is True. The second will execute it if Blah is not False, which is rather different!

I should write a blog entry on that particular "gotcha".

re: Reading Code Is Hard

No one — Mon, 14 Jun 2004 19:51:00 GMT

What is shadowing?

re: Reading Code Is Hard

Eric Lippert — Mon, 14 Jun 2004 20:11:00 GMT

What does this program do?

void foo(void)
{
int count = this->CountFrobs();
for( int count = 1 ; count < 10 ; ++ count)
{
print(count);
}
print(count);
}

That's shadowing. The inner variable shadows the outer local variable. Not all languages support shadowing, but C and C++ do.

re: Reading Code Is Hard

Christopher Hawkins — Mon, 14 Jun 2004 20:16:00 GMT

It sounds as though Jeremy is trying to teach non-coders to read code, which may not be entirely realistic.

re: Reading Code Is Hard

Robert W. McLaws — Mon, 14 Jun 2004 20:31:00 GMT

I read a great book recently (not yet released) that focused on a very simple premise:

Code craft is not about writing code that computers can read. A computer can understand o.e(q); but that doesn't mean you should use it.

No, being a true coder comes from the understanding that you are not writing code for a computer. You are writing a language that other PEOPLE will need to read and understand.

Some people would say "You should make sure you add lots of comments." But isn't the goal to write code that doesn't need to be commented? Shouldn't your code use a consistent, intuitive structure on every level, from the directory to the class library?

True masters of the craft write code that needs no comments, because it is completely apparent, through variable and function naming, what is going on. The only comments that should be neccessary are API documentation tags, which are wholly different from : 'Loop through the collection to enumerate the names

If reading code is hard, it's only because developers are poor communicators. I talked about this concept in more detail a few months ago here: http://weblogs.asp.net/rmclaws/archive/2004/01/30/65445.aspx

re: Reading Code Is Hard

Mike Dimmick — Mon, 14 Jun 2004 20:56:00 GMT

I know some developers who've moved from VB 6 to C#:

if ( blah == true )
{
}

Aaargh!!

re: Reading Code Is Hard

M. — Mon, 14 Jun 2004 21:46:00 GMT

There's a book on the subject:

http://www.spinellis.gr/codereading/

IMHO, it's very good.

Book on reading code

Duane — Mon, 14 Jun 2004 22:06:00 GMT

A good and perhaps unique book, all about how to read code:

http://www.spinellis.gr/codereading/

re: Reading Code Is Hard

Jeremy Kelly — Tue, 15 Jun 2004 05:12:00 GMT

Your post was interesting, but it didn't directly help my quandary. KC didn't include my entire post... I have been tasked with delivering a class on how to "read" source to troubleshoot issues. My role routinely involves utilizing these abilities to read, rationalize, and reverse engineer code, but how to convey these to others?

re: Reading Code Is Hard

Dan Shappir — Tue, 15 Jun 2004 10:26:00 GMT

Jeremy, my best suggestion would be: try to grasp the coding style of the person who wrote that code. Most of us have our own coding style, which are often quit unique, even when the company we work for attempts to enforce coding guidelines. Often encountering a different coding style results in cognitive dissonance - you feel a great urge to "fix" that code, to transform it to your own style. Resist that urge. Instead assimilate that style and use your understanding of it to understand the code. It may even help to write down the rules of this code as you come to understand them.

Also, try to take a top-down approach (there are even tools that can help you do that in some cases). Don't delve into functions you don't need to understand, you'll drown in the details (obviously in some cases you may not have a choice, for example if lots of globals are used).

Bottom line: to understand complex code requires humility. See this:
http://www.wilk4.com/humor/humore17.htm

Eric, I disagree with one of your rules:

> Variables with names like "i" are badness. You can't easily search code without getting false positives.

A variable name like "i" is badness if used as a global (oh the horror) or a member or even a parameter. It is IMO perfectly fine as an index for an inner loop, e.g.

for (int i=0; i < length; ++i) a[i] = i;

You never grep for such variables and the name "i" actually indicates the variable's use. OTOH this style does cause problems with languages that don’t support shadowing, such as JavaScript (which is why I like the functional style, where you don’t need such variables).

I would add the following rule: a function should never be more than two screens in length and a loop should never be more than one screen (I actually try to keep both much shorter than that).

re: Reading Code Is Hard

peterb — Tue, 15 Jun 2004 13:08:00 GMT

At least if you're writing C code, lint will complain if you write:

if (blah == TRUE) { ...

rather than

if (blah) { ...

Of course, that brings up the whole "Why the hell isn't lint part of the compiler?" fiasco.

re: Reading Code Is Hard

Eric Lippert — Tue, 15 Jun 2004 17:33:00 GMT

I agree that if you keep the loops short, you can get away with cheap indexers. But still, loops have this tendency to get longer and longer...

And it's not just grep, it's also searching using my editor's regexp search function which is easier if the variables are unique in the text.

I personally will write loop indexers as "iFoo", to call out that I'm indexing over an array of Foos. I know other people who prefer to use ii, jj, kk as their loop indexers. Short, clear, traditional, easy to search.

Reading Code Is Hard, Part Two

Fabulous Adventures In Coding — Tue, 15 Jun 2004 21:06:00 GMT

Make the code amenable to tools

Diomidis Spinellis — Tue, 15 Jun 2004 22:13:00 GMT

Another way to make the code amenable to tools: use a consistent coding style. If the function names in function definitions always start in column 1 you can find them (with your editor or grep) with the regular expression "^name".

re: Loop indexing

Diomidis Spinellis — Tue, 15 Jun 2004 22:21:00 GMT

I agree with the previous poster who said that a variable named "i" is not an unreasonable name for an array index in a short loop. Another poster then reccommended using iFoo for indexing over an array of Foos. We can actually do a lot better than that by letting the compiler do the job for us. Instead of an integer index we can declare a pointer to an object of the array. This ensures that we will never index objects of the wrong type. Integer array indices are not connected in any way with the object they index and therefore force us to use naming hacks like iFoo; pointers on the other hand carry with them the required type information.

How do I debug a problem in someone elses code

Larry Osterman's WebLog — Thu, 17 Jun 2004 19:49:00 GMT

re: Reading Code Is Hard

Andrew Shuttlewood — Fri, 18 Jun 2004 11:58:00 GMT

If I get a lot of false positives (as above), you can chain the output of grep into another grep with -v

so

grep -r perfExecuteManifest | grep -v perfExecuteManifestInitialize >output.txt will prune them.

But I accept it's still an arse, you have to KNOW about all of the possible false positives before you can do this.

re: Reading Code Is Hard

Petr Kadlec — Fri, 18 Jun 2004 12:56:00 GMT

And what about grep -w perfExecuteManifest ?

Teaching the Skill of Reading Code

JeremyK's [MSFT] WebLog — Tue, 29 Jun 2004 08:03:00 GMT

See Braidy Tester Read Code. Read, Braidy Tester, Read!

The Braidy Tester — Wed, 14 Jul 2004 18:45:00 GMT

Write Readable Code By Making Its Intentions Clear

you've been HAACKED — Fri, 20 Apr 2007 10:58:56 GMT

Write Readable Code By Making Its Intentions Clear

Community Blogs — Fri, 20 Apr 2007 13:21:59 GMT

I don’t think it’s too much of a stretch to say that the hardest part of coding is not writing code,

Write-only variables considered harmful? Or beneficial?

Fabulous Adventures In Coding — Fri, 07 Sep 2007 01:30:22 GMT

I haven't forgotten that I promised to describe one more place where we insert an explicit conversion

Reading Code Is Hard, Part Two

Fabulous Adventures In Coding — Thu, 11 Oct 2007 21:38:41 GMT

I was thinking about this a bit more and talking with Larry Osterman yesterday, and I came up with some