Tag: book

Review: Framework Design Guidelines, 2nd Ed. by Krzysztof Cwalina and Brad Abrams

Subtitle: “Conventions, Idioms, and Patterns for Reusable .NET libraries”. Highly relevant to Delphi Prism users, but you can very well eliminate that .NET part and apply this to writing libraries for Win32 using Delphi 2009 as well (or any prior Delphi version, for that matter).

When you write code with the intent of making it public and reusable, there are certain aspects of designing classes, interfaces, types and so forth, where we really need experience to come up with easy to understand and easy to use code. This book delivers 6 years worth of wisdom and experience from the .NET teams and we can all do well by picking their brains for reusable knowledge.

The book present a sensible set of lessons learned and goals to strive for. Without lecturing, and always exemplifying – we get a step by step journey through the different aspects of designing a framework. It is concisely written and easy to read, and it is not without humor.

The book is richly commented by the developers themselves, embellishing on the guidelines, sometimes including design regrets and mistakes made, and sometimes also hinting towards why you might want to break a guideline under certain conditions.

As Anders Hejlsberg write in the foreword: “The guidelines have served us well through three versions of the .NET Framework and numerous smaller projects, and they are guiding the development of the next generation of APIs for the Microsoft Windows operating system”.

I won’t delve into all the details of the content, but it covers the basics of how to design a framework by being roleplaying the consumer as well as testing it on your peers, good naming, type design, member design, extensibility, exceptions, as well as usage guidelines. It rounds off with a collection of common patterns such as aggregate components, async patterns, dependency properties, dispose pattern, factories, and many more. There is also a brief C# coding style convention section and a tutorial on using FxCop to enforce the framework design guidelines.

The book is not C# centric, but embellish the fact of .NET being a multi-lingual platform, and remind you to avoid certain constructs that may be too tightly bound to a specific language.

“Framework Design Guidelines (2nd Ed.)” by Krzysztof Cwalina and Brad Abrams (Addison-Wesley ISBN-13: 978-0-321-54561-9) falls under the collection of books that I wish I had available to read when I started out coding. Together with “Code Complete (2nd Ed.)” by Steve McConnell, it should be mandatory reading for every developer, regardless of language or development niche.

Highly recommended.

Understanding RESTful services

RESTful web services seem to be gaining in popularity over SOAP / RPC oriented web services, but what is a REST (Representational State Transfer) service, really?

The term was coined by Roy Fielding in his Ph.D. dissertation in 2000, so it is not really a new thing. Some people like to wave the term around like a new mysterious tool that only the chosen ones can understand and wield. Some authors like to dance around the topic without getting down to the elevator speech description and go into great and elaborate examples on how “RPC is too complex in this or that scenario, and this is why you should use REST instead”. Cut to the chase already!

One book that do actually get to the point, is RESTful Web Services by Leonard Richardson & Sam Ruby (O’Reilly, ISBN 0-596-23926-0). Easy read, good examples, sensible commentary.

So… what is REST ?

Key: The URI is our permanent and unique key to the content
Content: Can be anything, really, as long as it can be sent across the transport
Transport: HTTP (Get, Put, Update, Delete)
Transaction: Always one complete operation per REST object

Ok, so that might be a tad oversimplified, but it actually isn’t much more complicated than that. In a way, you can compare it to a file system, and depending on how you build your content, it can be cached like a file system, in your ISPs cache, the company firewall cache, and your desktop browser cache.

Was that too easy? Well, there are some areas that are not quite as well defined, such as content description, content discovery, and access control – but there are more than one way to Rome here. Eventually, some sort of best practice will probably emerge, but right now it is sort of every RESTful service for itself.

IMO, for a developer – the true challenge with REST is deciding on how to construct your data URIs and how to partition up your data so that they are easily and logically accessible. You have to consider such stuff as categories, filtering, time range, wildcards, etc. If you intend to cache the data, you also need to figure out versioning so that you don’t get stuck with stale data. On the coding side – the real action happens behind the http transport on your server, where you have to do your stuff to pack and deliver or unpack and store your data.

It turns out that REST is not even a bit mysterious. Some people just like to pretend that it is. You don’t need huge commercial complex frameworks to write a REST service. Come to think of it, Delphi is a great tool to write REST servers in. It has all you need: good parsing tools, database integration, http components, etc.