Another rant... But it is true. They are important.

There are certain conventions that should not be contravened (I looked it up in the dictionary, don't worry ;-p). Not only in software development. Conventions apply to all sorts of fields and day-to-day life situations. But they are very important in software development.

And yes, I've been burned by someone who did not follow them.

When I first read about the .Net Framework Guidelines, which later would became a highly recommendable book, I thought "Great, so they will close the debate forever about hungarian notation, m_ prefixes and why we all will become blind if we even think of using them...".

When I was read some opinions about them without actually reading the guidelines, my thoughts were more on the line of "Those things are only applicable if you are creating the framework itself and I am not doing that, I just have to get this thing done by yesterday and what is design by the way?".

When I began reading them in blog posts I thought: "Hey, they are not just justifying themselves, most of it makes sense."

And when I finally read the book I was very pleased because I thought: "Yes, it makes sense, but I strongly disagree with some of their points, because...blah, blah, blah". A question of maturity, I guess.

 

The point is, they are not the Holy Bible, but they provide a great insight on why design matters and more than a handful of useful solutions. Borrowing from one of the authors: "Many assume that the Design Guidelines document is intended to be a repository of the best solutions to common API design problems. Let me get it straight right away. This is not the intention at all. The main purpose of the Design Guidelines is to achieve consistency in reusable library APIs."

We can see an example (of course chosen randomly, nothing to do with the matter that burned me and my team ;-p):

"In general, methods represent actions and properties represent data. Properties are used like fields, meaning that properties should not be computationally complex or produce side effects."

And this is very true. When someone invokes a property getter on a type he expects to retrieve data more or less instantaneously. They should not care what sort of processing behind the scenes it's happening. Invoking twice a property? Sure! nothing major will happen, won't it? Something good, if anything. Let them think of lazy loading an expensive (but not so expensive) or reusable resource, some internal checks or similar.

In their book, the authors refer to the "principle of least surprise" in the context of API design quite a few times. For me, it's one of the most important principles and I could not agree more with them. Let's face it: Developers hate being constantly surprised. They love having the control. They love thinking "I know what this is doing inside". When a rebel API strikes back, they do not like it. I DO NOT LIKE IT EITHER.

Properties should be less more than glorified fields. They must not bring down your application because you invoke them. They must not be a shortcut to a well known (when dealing with the API) performance-hog. You see a property and think "it's a property, a reference to the context from which I retrieved my instance, surely they cached the instance for not incurring on a performance hit when calling a property getter, otherwise it would be a method, wouldn't it?... they are good, they play accordingly to the rules they write about".

But no. They don't. It is bad when someone developing and application does not follow rules and conventions. But it is inexcusable when some powerful software company, full of knowledgeable resources, charging a lot of money for a product that IS AN API and a set of tools on top of that, does it. And they did it and they made us waste our time.

All said, the reader will understand why, while I was trying to chase a nasty performance issue in our project mere hours before showing it to the client as part of our monthly sprint demo, I found out that one of the problems we had was accessing a property inside a loop, my degree of "lovability" sank to negative levels, while my swearing-in-foreign-or-even-dead-languages level soared proportionally.

And for those of you who are thinking "What if they put a remark in their documentation saying that calling a property might be expensive?" I would say: "Those remarks would be unnecessary if the API was well designed. Forcing developers to look at documentation because of design flaws looks a bad deal to me".

If anyone wonders which product we were using, I recommend having a look at the tags of the posting... And now, I feel marginally better.