| Date: | April 6, 2007 / year-entry #121 |
| Tags: | other |
| Orig Link: | https://blogs.msdn.microsoft.com/oldnewthing/20070406-00/?p=27343 |
| Comments: | 53 |
| Summary: | Design for readability. Even if you don't intend anybody else to read your code, 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. When I advised against the use of BOOL... |
Design for readability. Even if you don't intend anybody else to read your code, 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. When I advised against the use of An anonymous commenter pointed out that hovering over the offending function in the IDE shows the function declaration. While that may be true, it's still not a great solution. First, it means that you have to read code with your hand on the mouse. Second, it means that you can't skim code because you're going to hit a Imagine if you had to read code that had gone through a ROT-13 filter. Sure, the IDE might help you by decoding the text under the cursor if you hover over it, but even instant help isn't fast enough. And finally, another commenter pointed out that this doesn't help you if you're reading code anywhere outside your IDE. It might be in a magazine, in a printout, in a bug report, on an overhead projector, on a web page, in a Usenet message, or in an email message. Good luck getting Intellisense to help you out there. |
Comments (53)
Comments are closed. |
PingBack from http://informativeposts.info/code-is-read-much-more-often-than-it-is-written-so-plan-accordingly/
Funny; 10 minutes ago I thanked myself for doing that in a project I wrote two years ago.
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.
PingBack from http://www.red-sweater.com/blog/316/coding-for-readability
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.
PingBack from http://newyorktimesblogs.info/code-is-read-much-more-often-than-it-is-written-so-plan-accordingly/
PingBack from http://falloutboyblogs.info/code-is-read-much-more-often-than-it-is-written-so-plan-accordingly/
“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
PingBack from http://chaosinmotion.com/blog/?p=47
About a week ago, Shawn wrote a post about different types of code , and how he designs them. In a few
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:
“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
====
Dammit, Knuth got there first. Again.
;-)
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)
or
belongs_to :printable, :polymorphic => true
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.
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).
Yup. For another take on this, see Scott Meyer’s article: http://www.aristeia.com/Papers/IEEE_Software_JulAug_2004_revised.htm
PingBack from http://www.developers.org.ua/archives/koldovsky/2007/04/07/more-equal-code/
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.
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.)
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.
PingBack from http://outofcheese.org/2007/04/07/designing-for-readability/
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.
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…
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.
Old news, Raymond. Old news.
"Programs must be written for people to read, and only
incidentally for machines to execute."
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.
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.
""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.
IDE-reliance is lame.
The side text is on top of the article and comment text on this page. Yuck.
True, true about reeding code…
p.s. Am I alone who thinks, that "PingBack"s should be banned?
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."
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.
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 :-)
"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.
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.
PingBack from http://lpetr.org/blog/archives/dividing-code-into-functions
"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.
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."
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.
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.
"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.
PingBack from http://www.davidpaulrobinson.com/2007/04/09/commented-code-doesnt-equal-clear-code/
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.
PingBack from http://alittledrop.com/2007/04/10/my-pet-theory/
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?
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 ;)
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.
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.
(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.
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.
PingBack from http://lonesysadmin.net/2007/04/17/links-for-2007-04-17/
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.
PingBack from http://blog.tetrack.com/2009/01/on-code-quality-read-your-code/