Code is read much more often than it is written, so plan accordingly

Kaveman’s Daily Feed of Informative Blogs » Code is read much more often than it is written, so plan accordingly

Fri, 06 Apr 2007 17:57:33 GMT

PingBack from http://informativeposts.info/code-is-read-much-more-often-than-it-is-written-so-plan-accordingly/

re: Code is read much more often than it is written, so plan accordingly

Richard Avila — Fri, 06 Apr 2007 18:08:02 GMT

> Design for readability.

Funny; 10 minutes ago I thanked myself for doing that in a project I wrote two years ago.

re: Code is read much more often than it is written, so plan accordingly

dave — Fri, 06 Apr 2007 18:11:25 GMT

I've come to view programming as 'an act of explanation', and it's much more important for me to explain to myself how to do something than it is for me to explain to the computer to do it.

Red Sweater Blog - Coding For Readability

Red Sweater Blog - Coding For Readability — Fri, 06 Apr 2007 18:23:09 GMT

PingBack from http://www.red-sweater.com/blog/316/coding-for-readability

re: Code is read much more often than it is written, so plan accordingly

Mike Weiss — Fri, 06 Apr 2007 18:49:42 GMT

Two other common cases where Intellisense won't help you:

1) Even in the IDE its not always working. Often it's just breaks. Mainly this happens in VC++. 2005 is better, but not as reliable as C# or VB.NET (or VB6's IDE). I'm not ragging on the VC++ IDE team - I'm amazed that it works at all.

2) You're looking as code through source control or some type of diff tool.

york times » Blog Archive » Code is read much more often than it is written, so plan accordingly

Fri, 06 Apr 2007 19:13:20 GMT

PingBack from http://newyorktimesblogs.info/code-is-read-much-more-often-than-it-is-written-so-plan-accordingly/

out boy » Code is read much more often than it is written, so plan accordingly

out boy » Code is read much more often than it is written, so plan accordingly — Fri, 06 Apr 2007 19:55:34 GMT

PingBack from http://falloutboyblogs.info/code-is-read-much-more-often-than-it-is-written-so-plan-accordingly/

re: Code is read much more often than it is written, so plan accordingly

Adrian — Fri, 06 Apr 2007 20:00:48 GMT

“Let us change our traditional attitude to the construction of programs. Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.” —Donald Edwin Knuth

“Programs should be written and polished until they acquire publication quality.” —Niklaus Wirth

Development Chaos Theory » Words of Wisdom

Development Chaos Theory » Words of Wisdom — Fri, 06 Apr 2007 20:25:50 GMT

PingBack from http://chaosinmotion.com/blog/?p=47

Optimizing for Readability

Cornflower Blue — Fri, 06 Apr 2007 20:32:40 GMT

About a week ago, Shawn wrote a post about different types of code , and how he designs them. In a few

re: Code is read much more often than it is written, so plan accordingly

Stefan — Fri, 06 Apr 2007 20:33:07 GMT

We can fix our own, but we also have to live with functions that are already take boolean values. And we have to worry about other non-self-documenting parameter values, such as "", -1, and NULL.

My "solution" is to comment each opaque parameter. For example, a CreateEvent() call looks something like this:

CreateEvent(NULL /*security*/, TRUE /*manual?*/, FALSE /*signaled?*/, NULL /*name*/);

It's not very pretty, but it's readable. (Alternatively, you could write a wrapper that uses enums and manifest constants but ... ew.)

re: Code is read much more often than it is written, so plan accordingly

dave — Fri, 06 Apr 2007 20:47:20 GMT

re me:

I've come to view programming as 'an act of explanation', and it's much more important for me to explain to myself how to do something than it is for me to explain to the computer to do it.

re Adrian:

====

Dammit, Knuth got there first. Again.

;-)

re: Code is read much more often than it is written, so plan accordingly

Dustin Long — Fri, 06 Apr 2007 21:40:30 GMT

Seconded on Stefan's approach. This is part of the reason I love when I'm able to use Lisp or Ruby. It's nice being able to use symbols for named boolean parameters like:

(load "file.lisp" :verbose nil)

belongs_to :printable, :polymorphic => true

re: Code is read much more often than it is written, so plan accordingly

asdf — Fri, 06 Apr 2007 22:05:29 GMT

Knuth's out of context quote is good but the idea he came up with is 100% garbage IMHO. I own 4 books done in "literate programming style" and they're nightmares to read compared to books that do things the lazy/normal way of pasting large blobs of code and then explaining what's going on.

re: Code is read much more often than it is written, so plan accordingly

Neo — Fri, 06 Apr 2007 22:37:17 GMT

I have a question now: What is the real way to do it then? Create an enum for everything - redefine 0 and 1 hundreds of times?

Something else [I'm no expert with the C/C++ functions (or Win32 API). I use it only from time to time, if .NET isn't offering what i need]: EnableWindow(false) means the window is disabled?!? Wow, that's weird! If I see EnableWindow(BOOL) I wouldn't really understand what this BOOl is for! I would search a method called DisableWindow that disables a window (ShowScrollbar is the same).

re: Code is read much more often than it is written, so plan accordingly

mikeb — Fri, 06 Apr 2007 23:22:28 GMT

>> I have a question now: What is the real way to do it then? Create an enum for everything - redefine 0 and 1 hundreds of times?

Yup. For another take on this, see Scott Meyer's article: http://www.aristeia.com/Papers/IEEE_Software_JulAug_2004_revised.htm

???????? ?????? ??????????. ?????????????????? ?????? ???????????? ?????????????? « ???????? ?????????????????????????? « developers.org.ua

Sat, 07 Apr 2007 00:24:49 GMT

PingBack from http://www.developers.org.ua/archives/koldovsky/2007/04/07/more-equal-code/

re: Code is read much more often than it is written, so plan accordingly

jamie — Sat, 07 Apr 2007 01:01:27 GMT

Indeed when I use an API that contains bool parameters, I create consts vars with reasonable names documenting the desired effect.

// create non-signaled auto-reset event for

// ... [some useful description here]

const BOOL bIsManualResetEvent = FALSE;

const BOOL bIsInitiallySignaled = FALSE;

CreateEvent(NULL,bIsManualResetEvent, bIsInitiallySignaled, NULL);

Null pointer parameters are nearly as bad.

Objective-C's solution is quite nice in this respect.

re: Code is read much more often than it is written, so plan accordingly

david_douglass — Sat, 07 Apr 2007 03:40:30 GMT

Thanks to discussions like these, I hope people (especially middle management) will start see how damaging contractors can be. Contractors are almost always judged (at least by the people approving the invoices) on how quickly they can get things done. They're also well aware they won't be kept around to maintain the code. Many systems are seriously and unnecessarily flawed from inception because of this dynamic.

Out of Cheese » Designing for readability

Out of Cheese » Designing for readability — Sat, 07 Apr 2007 12:46:21 GMT

PingBack from http://outofcheese.org/2007/04/07/designing-for-readability/

re: Code is read much more often than it is written, so plan accordingly

Igor — Sat, 07 Apr 2007 18:53:19 GMT

I agree that code should be readable but having readability above the quality is absurd.

I have recently read an article by Andrew Binstock at Intel Developer Services titled: "Intel Optimization Best Practices: No Magic, Just Discipline and Good Tools".

What bothered me the most was this part:

"Thoroughly document all assembly code -- you can't expect other developers to understand it."

My question is "WHY?"

Not "WHY SHOULD I DOCUMENT?" because documentation is a Good Thing™ but "WHY I CANNOT EXPECT OTHER DEVELOPERS TO UNDERSTAND IT?!?!?"

IMO, serious developers must know assembler and the platform they write code for. The others who don't, they are not developers in my book.

re: Code is read much more often than it is written, so plan accordingly

John — Sat, 07 Apr 2007 20:17:11 GMT

It seems that only us "old guys" come to this conclusion. I'm still wait to meet a young programmer (under 35) that knows jack about commenting code. It takes years of slogging it out to really grok the reason there are things like /* */

sigh.

re: Code is read much more often than it is written, so plan accordingly

Starfish — Sat, 07 Apr 2007 23:35:49 GMT

Any young guy who's inherited a horrible ream of spaghetti code and had to comprehend it ought to appreciate there's some value to the slash-slash, assuming they care about being good programmers themselves. I shouldn't expect my CS lecturers to tell me 'great commenting', I'd like to think it's the norm and any less is bad...

re: Code is read much more often than it is written, so plan accordingly

John C. Welch — Sat, 07 Apr 2007 23:37:13 GMT

""Thoroughly document all assembly code -- you can't expect other developers to understand it."

My question is "WHY?"

Not "WHY SHOULD I DOCUMENT?" because documentation is a Good Thing™ but "WHY I CANNOT EXPECT OTHER DEVELOPERS TO UNDERSTAND IT?!?!?""

So all you need to program to an API are the raw API calls? No documentation explaining what each one does, what it's for, what the ideal use case is, some possible pitfalls? No comments in header files explaining what is going on?

You're going to look at code you wrote 5 years ago, and without comments, *instantly* remember WHY you wrote it the way you did?

By itself, code only answers "what". It takes a human to answer "how", and comments to answer "why", especially if the code hasn't been looked at in a while. Self-documenting code is a myth, and one I wish would be taken out back and shot like Ol' Yeller with da hydrophobia.

Anyone who can't be bothered to write clean, neat, readable, properly commented code can't be bothered to be paid to write code at all.

re: Code is read much more often than it is written, so plan accordingly

Seth Werkheiser — Sat, 07 Apr 2007 23:47:56 GMT

Wow, I do basic HTML work for a major publication, and I can't tell you how annoying it is to work with old HTML coded pages. Most looks like it was done in FrontPage or Word or something. uggg. So yea - moving forward I code most everything to be human friendly, especially for the point of, "hey. 12 months from now I might need to change something."

Good post.

re: Code is read much more often than it is written, so plan accordingly

Eh — Sat, 07 Apr 2007 23:57:12 GMT

Old news, Raymond. Old news.

re: Code is read much more often than it is written, so plan accordingly

Johannes Rössel — Sun, 08 Apr 2007 02:52:38 GMT

"Programs must be written for people to read, and only

incidentally for machines to execute."

- Abelson & Sussman, Structure and Interpretation of Computer Programs, preface to the first edition.

I once hoped everyone who codes a little more than just a few lines a year ultimately comes to this conclusion but hope is gone now. But I've seen that it is of great help when people are forced to work in a team on the same code. Ultimately they will adapt to a style that is readable and they'll even comment.

re: Code is read much more often than it is written, so plan accordingly

pwb — Sun, 08 Apr 2007 07:48:35 GMT

IDE-reliance is lame.

re: Code is read much more often than it is written, so plan accordingly

bogus — Sun, 08 Apr 2007 10:06:14 GMT

The side text is on top of the article and comment text on this page. Yuck.

re: Code is read much more often than it is written, so plan accordingly

Ma — Sun, 08 Apr 2007 11:28:44 GMT

True, true about reeding code...

p.s. Am I alone who thinks, that "PingBack"s should be banned?

re: Code is read much more often than it is written, so plan accordingly

Sun, 08 Apr 2007 15:14:23 GMT

david_douglass - *all* programmers are judged by middle management on how quickly they can get stuff done. Whoever you are and however you obtain work, you're being paid for tangible results. Nothing else.

Unfortunately, Goodness comes with a premium that most people don't wish to pay. If you're really concerned about this, become a contractor and market yourself to those who care about quality.

re: Code is read much more often than it is written, so plan accordingly

Michael Stiefel — Sun, 08 Apr 2007 16:57:28 GMT

As is frequently the case, Gerry Weinberg said it best in 1971, in the "Psychology of Computer Programming" (Chapter 1, 'Reading Programs'):

"There are many reasons why programs are built the way they are, although we may fail to recognize the multiplicity of reasons because we usually look at code from the outside rather than by reading it. When we do read code, we find that some of it gets written because of machine limitations, some because of language limitations, some because of programmer limitations, some because of historical accidents, and some because of specifications--both essential and inessential. But for whatever reason a particular piece of code gets inserted into the final product, there are psychological aspects to the reason--which leads us to believe that studying programming as human behavior will bear numerous and not always expected fruits."

re: Code is read much more often than it is written, so plan accordingly

Jack — Mon, 09 Apr 2007 00:11:58 GMT

I've been working on a large project for many years. In 2003 all hell broke lose, and we were 'forced' to pump out a lot of code and saved time by dropping comments: The code was 'obvious' anyway. Now everytime a bug crops up in that code it's "Awwww Crap! 2003 Crapolla!"

Ever since then we comment liberally. Not beautiful, elegant comments: Just short brain dumps.

Comments are one of those things we're told to do and undestand, but until you break the rule you don't really appreciate it. Well Dumbasses like us anyway :-)

So true.

LanternLight — Mon, 09 Apr 2007 02:30:47 GMT

"there's still a very good chance that somebody will have to stare at your code and figure out what it does: That person is probably going to be you, twelve months from now."

Learnt that a long time ago. Wrote some superb Cobol code, I was really in the zone that day. 3 months later, it took me twice the (coding) time to work out my cleverness.

re: Code is read much more often than it is written, so plan accordingly

StepH ~ Tijmoe — Mon, 09 Apr 2007 19:37:23 GMT

Same things here... Mow, It re-read my code, even if I don't plan to change it 2 weeks after I've write it.

If i can easly re-read it, It simply it.

re: Code is read much more often than it is written, so plan accordingly

Igor — Mon, 09 Apr 2007 20:30:34 GMT

John C. Welch said: "So all you need to program to an API are the raw API calls? No documentation explaining what each one does, what it's for, what the ideal use case is, some possible pitfalls? No comments in header files explaining what is going on?"

You see, there is no amount of comments in the code that will help you and the like and I will tell you why. It is because you don't bother to READ. At least you haven't read or understood my comment.

I said that documentation is a good thing. Unfortunately, some programmers abuse /* ... */ and // for the sake of increasing their code line count.

Moreover, employers are often unwilling to pay for quality code.

Furthermore, I would expect a fellow developer reading my code to be able at least to look up API syntax in documentation. At least I was able to when I wrote the code and that't what API documentation is for, one should not have to duplicate it in the comment blocks.

In the age of such technology as cell phones with broadband, palm pilots, pocket PCs all having internet access anywhere on the planet please don't tell me it would be so difficult to look up an API on MSDN even if you are dealing with the code printout over the lunch.

Don't get me wrong, I am all for comments and documenting the code, but IMO they should say _why_ something is done in some particular way instead of wasting space on blindingly obvious things.

My all time favorite are comments like this:

a = b / 2; // we could use b >> 1 instead

Like if it matters at all today when compilers will optimize it to right shift anyway.

Believe me, I have seen a lot of comments like that one and the guys who write such code earn more money than I do even though the code itself is shorter than all the useless comments in it.

re: Code is read much more often than it is written, so plan accordingly

Jeff Staddon — Mon, 09 Apr 2007 20:43:56 GMT

"It seems that only us "old guys" come to this conclusion. I'm still wait to meet a young programmer (under 35) that knows jack about commenting code. It takes years of slogging it out to really grok the reason there are things like /* */"

Bravo! However, there are always exceptions. :-) I did however have the good fortune of spending most of my first 5 years doing maintenance programming so I gained a lot of experience that other young developers don't get. (Until their own code ages) There's no better way to learn (both good practices and things to avoid) than working on code with a history!

IMHO good comments are far harder to write than good code.

LeoTech » Blog Archive » Dividing code into functions

LeoTech » Blog Archive » Dividing code into functions — Mon, 09 Apr 2007 21:31:17 GMT

PingBack from http://lpetr.org/blog/archives/dividing-code-into-functions

re: Code is read much more often than it is written, so plan accordingly

Paul — Mon, 09 Apr 2007 23:44:11 GMT

"I agree that code should be readable but having readability above the quality is absurd."

Who said there was an either / or decision here - having readable quality code should be the goal surely.

re: Code is read much more often than it is written, so plan accordingly

Mr Cranky — Tue, 10 Apr 2007 01:28:10 GMT

Favorite example:

SR R4,R4 Clear register 3

Favorite quote (albeit probably apocryphal): "It was hard to write, so it should be hard to read."

re: Code is read much more often than it is written, so plan accordingly

Anony Moose — Tue, 10 Apr 2007 03:03:08 GMT

A) "Always-on internet access anywhere on the planet" is a myth. If you planet consists of "work, home, starbucks" then you need to get out more.

B) Looking up API syntax is easy, but looking up the reason for the API call in the first place is a little harder.

C) A crap API is crap, even with documentation. A good API avoids pathetic idiocy such as "several BOOL paramaters" and thus avoids the need for both comments and re-reading API documentation.

re: Code is read much more often than it is written, so plan accordingly

Norman Diamond — Tue, 10 Apr 2007 05:23:02 GMT

Friday, April 06, 2007 8:40 PM by david_douglass

> Thanks to discussions like these, I hope

> people (especially middle management) will

> start see how damaging contractors can be.

Please stop blaming victims.

> Contractors are almost always judged (at least

> by the people approving the invoices) on how

> quickly they can get things done.

Thank you for stopping blaming victims. But there's more.

Sunday, April 08, 2007 8:14 AM by S

> *all* programmers are judged by middle

> management on how quickly they can get stuff

> done.

Only sometimes. If you really get stuff done too quickly then your salary goes down and you don't get promoted. You have to make a show of putting in unpaid overtime, not sleeping, and getting the results of programming while brain-dead.

> Unfortunately, Goodness comes with a premium

> that most people don't wish to pay.

Bingo.

Monday, April 09, 2007 1:43 PM by Jeff Staddon

> IMHO good comments are far harder to write

> than good code.

Bingo.

Monday, April 09, 2007 6:28 PM by Mr Cranky

>Favorite example:

> SR R4,R4 Clear register 3

That machine's manufacturer once boasted that they developed an automatic code commenting utility. It generated really useful comments like that.

> Favorite quote (albeit probably

> apocryphal): "It was hard to write, so it

> should be hard to read."

That's from the excellent satire "Real Programmers Don't Use Pascal". What do you mean by apocryphal here?

Commented Code Doesn’t Equal Clear Code | David Paul Robinson

Commented Code Doesn’t Equal Clear Code | David Paul Robinson — Tue, 10 Apr 2007 05:44:37 GMT

PingBack from http://www.davidpaulrobinson.com/2007/04/09/commented-code-doesnt-equal-clear-code/

I not only read my old code I WATCH it.

sss — Tue, 10 Apr 2007 06:35:16 GMT

I came to the same conclusion a while ago. I was constantly being asked to update something I'd written 12 or more months ago. Before I started commenting my code it was a nightmare.

But now I go one better... and I can watch my code. I create a screenshot video of me walking myself through the code, how it works, what can be modified, how I was going to add the next feature the client asked for at first but cut at the end, etc. I speak as if I was talking to someone with my abilites who was looking at this code for the first time.

This has saved my bacon quite often. Sometimes I even do it Friday afternoon so I remember where I was come Monday morning.

The really neat part is the customer gladly pays me to make these videos. I tell them it is one of my services to them; keeps them from being dependent on only me. When I tell them this on first contact they feel very confident about hiring me.

In the end, they always come back for the update even though they I've given them everything they need to do it themselves. So, WATCH your code and only you will know what a newbee you were last year.

My Pet Theory « A Little Drop Of Cocoa

My Pet Theory « A Little Drop Of Cocoa — Tue, 10 Apr 2007 11:16:48 GMT

PingBack from http://alittledrop.com/2007/04/10/my-pet-theory/

re: Code is read much more often than it is written, so plan accordingly

Igor — Tue, 10 Apr 2007 12:01:01 GMT

Paul said: "Who said there was an either / or decision here - having readable quality code should be the goal surely."

Quality usually doesn't come with quantity. Or so they say.

Anony Moose said: "A) "Always-on internet access anywhere on the planet" is a myth. If you planet consists of "work, home, starbucks" then you need to get out more."

FYI I live in Serbia where we don't have Starbucks and broadband is still in development compared to all other countries around the globe including India but even such a cheap bastard as myself has cell phone with Internet access. So much about myths then.

Anony Moose said: "B) Looking up API syntax is easy, but looking up the reason for the API call in the first place is a little harder."

You are implying that people working with code don't have a clue about why APIs are getting called. If they don't then they need to find another job, otherwise they should stop bitching and moaning like a spoiled brats and earn their money for a change.

Anony Moose said: "C) A crap API is crap, even with documentation. A good API avoids pathetic idiocy such as "several BOOL paramaters" and thus avoids the need for both comments and re-reading API documentation."

I agree, but what is done is done and not dealing with it the same way the original writer did is just an excuse for lazyness.

Mr Cranky said: "It was hard to write, so it should be hard to read."

Tell me one good reason why it should be easy for *you* to read something which was hard for someone else to write?!?

Why I can't expect *you* to understand someone else's code without them having to write shedloads of comments?

And if I was the one who wrote that code and I get back to it to fix something, please spare me the crap that I won't be able to understand it after some time because it implies that I wouldn't be able to write it in the first place.

If it is both hard to write and hard to read code for you then you have picked wrong profession. Go drive a plow.

Show some dignity people and stop begging for work to be easy on you. If architects were designing buildings as sloppy as developers write code we would all be dead under huge piles of rubble by now.

re: Code is read much more often than it is written, so plan accordingly

Drak — Tue, 10 Apr 2007 12:36:03 GMT

If some function takes really weird parameters, I like the fact that in VB.NET you can do:

strValue = Settings.GetValue(strSettingName:="MySettingName", blnDefaultToNothing:=True)

This at least explains the True to people who didn't also write the GetValue function ;)

re: Code is read much more often than it is written, so plan accordingly

Hywel — Tue, 10 Apr 2007 14:10:48 GMT

There are some languages that lend themselves to better inherent readability. Named actual paramaters in Ada, for example, are superb for documenting, as are more explicit named block delimiters, like "end if" and "end loop" instead of the general and often poorly indented "}". (I particularly dislike that "{" and "}" rarely line up due to "{" so often being at the end of a line of code rather than at the start of the next line)

Forced intentation (indentation as block syntax) is a nice readability feature. Occam had that.

re: Code is read much more often than it is written, so plan accordingly

zzz — Wed, 11 Apr 2007 21:24:05 GMT

(tooltips etc) "And finally, another commenter pointed out that this doesn't help you if you're reading code anywhere outside your IDE."

If you really wanted, it shouldn't be too hard to create a new copy/print feature that would add the parameter types in either small print below the calls or color coded next to them. Or just a flip switch to turn this presentation on in the code editor.

Of course better yet would be to write better APIs but that doesn't really help with past mistakes.

re: Code is read much more often than it is written, so plan accordingly

Michiel — Thu, 12 Apr 2007 13:07:30 GMT

I've got a nice NOT_GOOD_AFTER(YYYY,MM,DD) macro that fails to compile if __DATE__ is later than that. Very useful to put in hacked code, so your code stops compiling and you are forced to get back to it.

The Lone Sysadmin » links for 2007-04-17

The Lone Sysadmin » links for 2007-04-17 — Tue, 17 Apr 2007 09:17:51 GMT

PingBack from http://lonesysadmin.net/2007/04/17/links-for-2007-04-17/

re: Code is read much more often than it is written, so plan accordingly

David Pritchard — Wed, 18 Apr 2007 01:07:32 GMT

I once talked to a young guy who was studying IT who confessed that he never wrote comments in code. He said that the reason he got into computing was "to avoid writing". Then we have those (like some contributors here) who believe that deducing the intentions behind densely-packed (and uncommented) C or assembler is some kind of programmers' rite of passage. All depressing and frustrating for language-oriented types like me.

It seems to me that people confuse two things: the syntax of code, and the purpose behind it. For me, the problem in understanding code (including my own), is knowing WHY I did something, rather than WHAT I did. In real software, not all of the logic leaps out at you from the screen. You need to explain it.

On code quality: read your code | TE chnology

On code quality: read your code | TE chnology — Thu, 29 Jan 2009 13:00:51 GMT

PingBack from http://blog.tetrack.com/2009/01/on-code-quality-read-your-code/