Posts Tagged ‘standards’
Review: Framework Design Guidelines
Framework Design Guidelines
I’m almost embarrassed to admit that I really enjoyed Framework Design Guidelines by Krzysztof Cwalina and Brad Abrams. I mean, it’s a book about coding standards.
Maybe I ought to get out more… but before I leave the glare of my monitor behind, I’ll type up my review.
Code is literature, not language
Computing languages, just like human languages, have grammar and syntax. There are correct ways to form sentences and paragraphs, with well-defined rules (and exceptions). Just like word processors can check spelling and verify basic sentence structure, most IDEs today can ensure your code will compile and run.
That doesn’t mean that your story or program is an easy or enjoyable read, though. Most newspapers have accumulated extensive guidelines for matters of style and substance, and most software companies have their own guides as well. If you’re writing as part of a team project, or writing programs intended to be used by other programmers, it’s important to make your code consistent, clear, and direct.
Just like many journalists keep a copy of The Associated Press Stylebook or the New York Times Manual of Style and Usage handy — even if they don’t actually work for the New York Times or the AP — lots of programmers keep a copy of Microsoft’s Framework Design Guidelines as reference.
Or they should. That’s probably my roots as a maintenance programmer showing.
Know your genre
Ideally, you’d want any code you write for other Windows programmers’ use to look as if it came from Microsoft itself. That is, you want it to feel like a natural extension of the .NET framework and not some third-party bolt-on with odd stylistic touches. You’d also like your code to use the full power and expressiveness of .NET, and not appear like some watered-down Java-esque port. (Far too many open source projects retain awkward Java-isms after being converted to .NET, in my opinion. NUnit is a notable exception.)
This helps your fellow programmers gain a better understanding of your code in less time. And it can also make your programming tasks easier, too. Just like design patterns can help you lay out your application architecture, programming guidelines can help you structure your code at the class or method level.
About the book
The Framework Design Guidelines covers a lot of ground in its 400 pages. It describes what conventions Microsoft uses when designing types, methods, and exceptions. It also describes the naming and design patterns that Microsoft uses in their public APIs. The topics are grouped by category and heavily cross referenced, making it easy to find your way around. The rationale of each guideline is explained, and the authors indicate the strength of each recommendation by marking it with the terms Do, Consider, Avoid or Do Not.
But the best part of the book is the stories and comments given by members of the Microsoft team. These are sprinkled throughout the book and give insight into why the guideline exists. Some of these discuss lessons Microsoft learned the hard way, places in the .NET Framework where the rules are violated, and how real-world programmers feel about certain guidelines. You can get a flavor of these by checking out the Framework Design Guidelines section of Brad Abrams‘ blog.
If you find his posts interesting or helpful, you’ll feel the same way about the book. Highly recommended.
The Times, They Are A-Changin’
Recently, I made a plea for the adoption of Universal Coordinated Time (UTC) in computer applications. It’s a sensible recommendation, and I stand behind it.
The folks working on HTML 5 are proposing a <time> element for the new standard. This makes sense to me. It will help eliminate some of the objections people have raised to the datetime design pattern proposed by the microformats team.
So, problem solved, right? We use UTC for time, and the usual calendar notation for dates. Neat.
Wait a minute. By “the usual” calendar notation, do we mean the modern Gregorian calendar, or…
There’s always a catch
Peter-Paul Koch, a.k.a. PPK, author of the quirksmode blog, reminds us that calculating historical calendar dates is hard. Really, really hard.
He provides an overview of the major calendar reforms in the Western world and points out that the reforms were adopted by different countries at different times. So forming a consistent timeline requires a knowledge of both time and place.
And many important historical dates float. The rules that determine when Easter occurs in the church calendar are complicated, and Orthodox and Catholic calendars disagreed for many years. In the medieval period, years were often numbered according to the local monarch’s reign. In Roman times, extra days were added to the official calendar by decree to prevent the seasons from drifting too far out of line.
If we want to make the <time> element safe for historical use, programmers would have to deal with this mess.
Leave it to the historians
As useful as having universal, consistent <time> element metadata would be, that’s just too hard. Frankly, I skimmed the last bits of PPK’s article myself, and I’m actually interested in the issue. Most working programmers won’t bother.
While it’d be nice to have trustworthy time data, we’re not likely to get it. The standard should reflect that. I vote for assigning a cutoff date for the <time> element. January 1, 1970 works for me.
Digital Watches are a Pretty Neat Idea
The Hitchhiker’s Guide to the Galaxy opens with the following quote:
Far out in the uncharted backwaters of the unfashionable end of the western spiral arm of the Galaxy lies a small unregarded yellow sun.
Orbiting this at a distance of roughly ninety-two million miles is an utterly insignificant little blue green planet whose ape-descended life forms are so amazingly primitive that they still think digital watches are a pretty neat idea.
Though it was published three decades ago, the quote is relevant today. Not only because of our continuing enthusiasm for digital watches, in all their forms, but because our neat little clocks are still amazingly, stunningly primitive.
Computers Can’t Tell Time
From the Y2K bug to the recent Zune bug, the inability of computers to tell time properly — and the inability of programmers to process dates and times correctly — leads to recurring problems.
While some tech bloggers feel the issue is poor datetime programming practices, I think the issue is more fundamental than that. Why else would an established software platform vendor like Microsoft still be struggling to come up with a decent datetime implementation?
The problem is simply that computers can’t tell time. Or rather, that computers worldwide can’t agree on what time it is.
A history lesson
In the early prehistory of the Information Age — prior to 1970 — computers were large, unwieldy assemblages of equipment. ENIAC filled an entire room. Mainframes and supercomputers, descendants of those early digital beasts, share two characteristics with the early computing devices.
- They are not portable.
- They do not communicate with other computers, or if they do so, they usually determine the operating environment of the other terminal computers.
Personal computers, even today, have yet to shake some of this legacy. The upshot of this is, your computer thinks its clock is always right. It never checks the position of the sun, or better yet, checks with the International Bureau of Weights and Measures to get the Universal Coordinated Time. As a result, most computers today rely on the accuracy of their internal clocks, which are typically set to local time or the time at the chip factory.
Some operating systems will adjust this for you. If you’re running Microsoft Windows, for example, you’ll default to U.S. Pacific Standard time. Which is wrong for most of us on the planet, but you have to pick somewhere to start, right?
All your base are belong to us
I know, you’re thinking, “All that crappy legacy left over from the mainframe days. Can’t we scrap it and move on?” Well, buckle up, friends, because there’s far more legacy thinking involved in timekeeping than that! Our system for time is based on work originally done in ancient Sumeria.
The Sumerians used a sexagesimal number system, which is almost as interesting as it sounds. Programmers are used to the everyday decimal number system, the binary number system, and hexadecimal. But base-60 is a complicated system indeed, with many fascinating properties, including the fact that it’s evenly divisible by the first six counting numbers.
So the reason why hours have 60 minutes and minutes have 60 seconds is all the Sumerians’ fault. As is the convention that a circle has 360 degrees.
And yes, they tried hard, but 360 is not quite the number of days in a calendar year. But they felt it was close enough. Though after two millennia, they’d made April Fools of many Catholics.
A modest proposal
My point? Math is hard, and converting between different numeric systems makes it harder, and when real life calendars don’t quite fit into a neat mathematical box, you’ve got the makings of a complicated system that’s ripe for failure. So fail we do — and often!
In the interests of making one tiny, tiny optimization in this all-too-complicated matter of time (And we haven’t even factored in general or special relativity yet!), I propose that we all adopt UTC immediately. Forget about daylight savings, forget about time zones: UTC and datetime calculations are troublesome enough without having to worry about localization.
We now have a globe-spanning GPS system, constantly beaming timing signals to a wide array of portable devices. Our laptops, workstations, minicomputers and mainframes ought to use these as well. Let’s all synchronize our neat digital watches.
Ready? Mark!
