Design Guidelines Digest

re: Design Guidelines Digest

Frank Hileman — Tue, 28 Sep 2004 23:36:00 GMT

-- "Do not require users of your APIs to instantiate multiple objects in main scenarios. Simple tasks should be done with new statement." I could not understand the second sentence. Do you mean "done with additional statements"?

-- "Do name types and properties with nouns or noun phrases." This is nice, but often I cannot think of a noun for a property, especially boolean properties. Perhaps there is another suggestion as well?

-- The Aggregate design and scenario planning suggestions are great.

-- "Do not seal types unless you have a strong reason to do it." This implies more testing, since unsealed types must be tested in derived class scenarios, as well as all the usual scenarios. You are putting a greater burden on the designer and implementer by asking them to leave things unsealed -- costs that may not be recognized. Perhaps this cost should be mentioned.

-- "Do not create mutable value types." It is impossible to change one property on a value type without calling a constructor, if it is immutable. This can produce clumsy code, especially when you need to put the value type "back" into something (like an array). For example, the Font class, though not a value type, is immutable and extremely clumsy.

-- "Avoid public nested types." I thought it was recommended to use an nested struct Enumerator type for enumerators? At one point I picked up this idea from MS.

re: Design Guidelines Digest

Krzysztof Cwalina — Wed, 29 Sep 2004 07:11:00 GMT

Thanks for pointing out the mistake. The sentence should say “Simple tasks should be done with one new statement.” And also properties can be named with adverbs and other phrases indicating an attribute of an entity. I will try to fix it. Thanks again.

As to not sealing, we very frequently get push back on this one. In fact, I had to justify this guideline internally today. Here is the justification I provided:

Please note that the following guideline says to avoid virtual members. Inheriting from a type that has no virtual members has very minimal implications on the base type. If there are no protected fields, the subtype really cannot modify any behaviors of the base.

Also, please note that the guideline does not ban sealing types if you have strong reasons to. For example you have virtual members and you cannot seal them.

Developers/Customers often want to inherit from such types to add helper methods, apply attributes, or rename the type. They get very frustrated and we get lots of negative feedback when we seal types without a strong justification. Therefore we (Microsoft) have made a tradeoff; we seal very dangerous types and leave the less dangerous unsealed. We are conscious that sealing all across the line would be probably safer, but would be less flexible for our customers. Again, it’s a tradeoff and the guideline is a judgment call.

Immutable types are indeed not so convenient. The problem is that mutable value types are very error prone. See Peter Golde’s post on "Mutable value types considered harmful" (http://peter.golde.org/2003/10/13.html#a16).

The nested type guideline is a general guidance, hence “avoid”. There are cases where nested types are ok or even preferable (collection specific enumerators are one such case). This issue is described in more detail in the full version of the Design Guidelines.

re: Design Guidelines Digest

Ripster — Wed, 29 Sep 2004 12:05:00 GMT

A brief antithesis

We have:
"Do not use of shortenings or contractions as parts of identifier names. For example, use GetWindow rather than GetWin"

But also:
""EventArgs" for types inheriting from System.EventArgs."

Slight contradiction, maybe it should have been EventArguments :-)

re: Design Guidelines Digest

Frank Hileman — Wed, 29 Sep 2004 16:28:00 GMT

"new statement" -- That phrase is ambiguous as it can be interpreted two ways. As a statement using the "new" operator, or an additional statement.

I understand why Peter Golde was confused by mutable types, but mutable structs also have the potential to produce more efficient optimized code by the jitter. If not now, perhaps in the future. For example if you want to change all the x values of points in a huge array, with an immutable struct you must copy over all the y values as well. As far as I know it is only possible to modify an embedded struct in an array. But that is enough reason right there I think to justify mutable structs, since arrays can be giant, aside from the clumsiness argument.

To get rid of the confusion caused by mutable structs in Peter Golde's case, I would recommend avoid creating structs that contain reference variables (references to objects). The compiler can catch property assignments to temporaries.

re: Design Guidelines Digest

Krzysztof Cwalina — Wed, 29 Sep 2004 17:45:00 GMT

Ripster, you are right that there are many places in the guidelines and framework that can be seen as contradictions. History, schedule, “design by committee”, and finally simple mistakes cause them. I wish the guidelines and the framework were perfect (from my point of view of course :-)), but this is really not possible given the complexities. As the owner of the project I used to get frustrated with any of the “flaws”. Brad Abrams cured me saying “it’s way better than it used to be”. :-)

re: Design Guidelines Digest

Mark Miller — Wed, 29 Sep 2004 21:11:00 GMT

It might be helpful to have links from the each of the "distilled" guidelines to their corresponding full explanations in the full design guidelines site.

On the frustration with "flaws"... If there were no flaws, we might not see the value in seeking to prevent them with guidelines. :)

re: Design Guidelines Digest

peter — Fri, 01 Oct 2004 03:38:00 GMT

Can you possibly post a PDF version of the word doc?

Peter

API Design Guidelines Digest

C#deSamurai — Fri, 01 Oct 2004 03:48:00 GMT

API Design Guidelines Digest

C#deSamurai — Fri, 01 Oct 2004 15:52:00 GMT

re: Design Guidelines Digest

Christian — Fri, 01 Oct 2004 16:13:00 GMT

"Do prefer classes over interfaces."

I try and work Test first which says to favour interfaces over classes. This is because it affords the developer more options to "mock" / stub an object he's code must collaborate with if that object is behind an interface.

Mocking a collaborating object is an important tool in the test first developer’s toolkit.

Thanks
Christian

Blog link of the week 40

Daniel Moth — Sat, 02 Oct 2004 12:49:00 GMT

http://www.zen13120.zen.co.uk/Blog/2004/10/blog-link-of-week-40.html

Krzysztof Cwalina: Design Guideline Digest

Lance's Whiteboard — Tue, 05 Oct 2004 03:21:00 GMT

re: Design Guidelines Digest

Krzysztof Cwalina — Fri, 08 Oct 2004 00:09:00 GMT

Peter, please email me at kcwalina@microsoft.com and I will send you PDF version of the digest.

Christin, I have a post on classes vs. interfaces on my "todo" list for blogging, and once I get to it, it will provide much more through reasoning for the guideline. But quickly to address you comment; a pure abstract class is no worse than an interface in terms of the flexibility that you describe.

re: Design Guidelines Digest

The Ugly One With The Jewels — Sat, 09 Oct 2004 19:04:00 GMT

"Do prefer constructors over factory methods"

this one is rather weird and - if followed blindly - it can have a negative impact on extensibility and maintainability

why would you enforce a constructor and ignore the obvious benefits of a factory (f.e. ability to plug a different implementation of an interface, ability to return cached instances instead of creating new ones, ability to return a single instance, etc, etc)?

re: Design Guidelines Digest

Krzysztof Cwalina — Tue, 12 Oct 2004 03:36:00 GMT

Yes, if the guideline is followed blindly, it can have a negative impact. The same holds true for the large majority of other guidelines. With the exception of naming conventions and some small number of design guidelines (for which the only justification is consistency), guidelines are not to be followed blindly. They are just good rules of thumb (starting/default points). If you find yourself violating the guidelines from time to time and you have a good reason, it’s ok (if you violate them most of the time then either we have developed bad rules of thumb or you indeed are doing something that is not consistent with the guidance).
Also on general note, I now see clearly the problem with the Digest. It’s short, but it forced me to delete all the justification and background that the original document has. Without the background info, it’s really difficult to judge whether not adhering to a guideline is the right thing or not. For example, here is the full text of the factory vs. constructor guidelines: http://blogs.msdn.com/kcwalina/archive/2004/10/11/241027.aspx

Factory vs. Constructor Guidelines

Alex Hoffman Weblog — Fri, 15 Oct 2004 03:33:00 GMT

An update to the Factory vs Constructor design guidelines ...

Factory vs. Constructor Guidelines

Alex Hoffman Weblog — Fri, 15 Oct 2004 03:36:00 GMT

An update to the Factory vs Constructor design guidelines ...

re: Designing .NET Class Libraries videos coming soon

Brad Abrams — Fri, 21 Jan 2005 00:08:00 GMT

General C# guidelines

Wouter van Vugt — Fri, 12 Aug 2005 22:16:20 GMT

Qualche link, documentazione e blog

Technology Experience — Tue, 07 Feb 2006 16:10:57 GMT

Progettare un'applicazione dalla UI

Technology Experience — Wed, 29 Mar 2006 17:58:24 GMT

info-bus.com Blog » Api design principles

info-bus.com Blog » Api design principles — Fri, 02 Jun 2006 21:57:23 GMT

PingBack from http://info-bus.com/blog/2006/06/02/api-design-principles/

» The obvious API - The Morning Toast

» The obvious API - The Morning Toast — Thu, 31 Aug 2006 07:49:12 GMT

PingBack from http://www.morningtoast.com/index.php/2006/08/the-obvious-api/

General C# guidelines

Wouter van Vugt — Thu, 31 Aug 2006 20:53:44 GMT

An interesting general code guideline . Most things will sound familiar to the more experienced developer,

Data Access Layer 101

StrangeLog - Il blog di Andrea Saltarello — Thu, 14 Sep 2006 16:20:52 GMT

Data Access Layer 101

StrangeLog - Il blog di Andrea Saltarello — Thu, 14 Sep 2006 16:21:45 GMT

Forse ha ragione David: la mia risposta al post di Giulio (per quanto sintetica e quindi non esaustiva) non

Data Access Layer 101

StrangeLog - Il blog di Andrea Saltarello — Thu, 14 Sep 2006 16:24:39 GMT

Program to an interface, not an implementation

StrangeLog - Il blog di Andrea Saltarello — Wed, 24 Jan 2007 00:53:04 GMT

Discussioni come questa sono un classico, e classica

links for 2008-02-04 « dstelow notes…

links for 2008-02-04 « dstelow notes… — Tue, 05 Feb 2008 02:30:36 GMT

PingBack from http://dstelow.wordpress.com/2008/02/04/links-for-2008-02-04/

Framework Design Guidelines Digest v2

Krzysztof Cwalina — Thu, 10 Apr 2008 00:36:10 GMT

Almost 4 years ago, I blogged about Framework Design Guidelines Digest . At that time, my blog engine

re: Design Guidelines Digest

Andrei Rinea — Sun, 25 May 2008 17:20:23 GMT

Regarding "Do not expose public fields. Use properties instead" I always saw this done in practice but was never sure why.

I suppose you can't tell from the class instance when the field is accessed? Or?

re: Design Guidelines Digest

Filip — Thu, 20 Nov 2008 11:12:39 GMT

The link to Full Design Guidelines does not work. Can you fix it please?

re: Design Guidelines Digest

kcwalina — Tue, 09 Dec 2008 22:03:39 GMT

Thanks Filip! I fixed the link

Design guidelines | hilpers

Design guidelines | hilpers — Wed, 21 Jan 2009 20:44:49 GMT

PingBack from http://www.hilpers.it/2655011-design-guidelines

Krzysztof Cwalina Design Guidelines Digest | fix my credit

Krzysztof Cwalina Design Guidelines Digest | fix my credit — Wed, 17 Jun 2009 04:33:19 GMT

PingBack from http://fixmycrediteasily.info/story.php?id=10161

Krzysztof Cwalina Design Guidelines Digest | Outdoor Decor

Krzysztof Cwalina Design Guidelines Digest | Outdoor Decor — Fri, 19 Jun 2009 07:14:48 GMT

PingBack from http://outdoordecoration.info/story.php?id=1823