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.
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.
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.
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.
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…
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.
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.
What I was actually looking for was an equivalent to Red Gate‘s SQL Packager for the Firebird database. SQL Packager is a useful application that makes it easy to package and deploy database schema upgrades. Sadly, all of Red Gate’s tools are for Microsoft SQL Server only.
My next step was to look through the list of admin tools on the Firebird website. And while there’s a huge selection of tools available for Firebird, I couldn’t find anything that would help me deploy schema and data upgrades. It was a bit surprising, actually, since one of Firebird’s strengths is how easy it is to embed inside other software applications. (If I’ve missed an application that can do this, please let me know!)
During the course of my investigations, I downloaded several different tools for managing Firebird. I’m a fan of the fast and free FlameRobin, but it’s still in development and doesn’t do everything I need. Sometimes a full-featured IDE is required, and I found two that fit the profile.
The first was SQL Studio from EMS Database Management Solutions. I appreciated their customer support and the breadth of features. But ultimately, I decided upon Firebird Maestro. The differences between the two IDEs were small, but Firebird Maestro had a better tool for producing database diagrams. Since Infovark has developers working halfway around the world from each other, having a good database diagram to reference is a must. Firebird Maestro also had a simple wizard for scripting out the schema and data into a single file. We put this text file into Subversion so that we have our database structure under version control.
It won’t help me deploy an update, but I’ve had to do that sort of thing by hand before, and I suppose I can do it again. But sometimes when you look for something you find something else just as good.
Our build server wasn’t producing the same results as our local development machines. The same C# code yielded two different sets of code libraries. After much head-banging and hand-wringing, we finally traced the problem to an obscure error in the way Visual Studio 2008 handles
Basically, the Visual Studio IDE doesn’t handle the CopyLocal setting properly. This post from paraesthesia set us on the right track.
I have no idea what caused the problem. We had the same versions of the .NET Framework and Visual Studio 2008 installed on all our machines. The code was exactly the same. Apart from the build machine being Windows Server 2003 and out development machines being Windows XP, I can’t think of any other differences. But somehow the code libraries weren’t getting copied in the same way.
Just another adventure on our way toward the Beta release…
I ran into a problem yesterday. I’d sent a HTTP POST request to a collection of resources on our RESTful web service. Our server responded with an
HTTP 201: Created status code and the URI of the new resource in the
And then… nothing happened.
This was not what I was expecting. I expected my web browser to follow up with a GET request to the URI I’d provided. But Firefox 3 wasn’t biting. A problem with Firefox? I checked in IE8 and Google Chrome and got the same behavior.
Had I misread the HTTP spec? Did I misunderstand the REST pattern? I grabbed for my worn copy of RESTful Web Services. Nope.
HTTP 201 seemed to be the right status for this situation.
Had I blundered into some common error? I checked Stefan Tilkov’s useful list of REST Antipatterns. But I couldn’t find anything that quite matched my situation.
I started Googling, but couldn’t find much apart from this question about HTTP Post on Stack Overflow. There were some cryptic responses (to which I’ve added my own answer now).
The answer is that while web service clients will often “take the hint” provided by a
HTTP 201: Created response, web browsers won’t. If you actually want a web browser to go somewhere else, you need to send a status code in the 3xx series. In this situation, the status code you want is
HTTP 303: See Other.
Once I changed the status code returned by the server, all the web browsers followed up the response with a GET to the new URI.