Design Guidelines, Managed code and the .NET Framework
Krzysztof spilled the beans... We just started working on the 2nd edition of the Framework Design Guidelines... Krys gives some hints on the kinds of things we will be covering .NET Framework 3.0 and .NET Framework 3.5 including LINQ and other cool new framework features. I would not expect the book until LATE '08, so if you were planning to buy the first edition, please go ahead ;-)
I'd love to hear your thoughts and feedback.. what should we cover? What changes should we make? What new annotations should we get?
Updated: fixed the Edition\Volume issue Mel pointed out...
I'd like to see it doubled in length! Seriously, that book is one I wish every .Net developer had...consistent-looking code goes a long way to the kind of code that is easy to maintain on a team level, and when it comes from the folks who write the root level library, it holds a lot more weight.
I've mentioned a few on Krzysztof's blog, but I'll add that I'd like to see you get into XML documentation a little bit...I never ever see it used in any .Net code I've worked with to the point of creating MSDN-style documenation, but it's a good habit to get into, especially for documented frameworks (it's something I've tried to do for a while, but it's been so long since I've looked at the output for any of my commented code that it's probably using the wrong tags)
This is really great news. I'll post some topics I'd like to see mentioned in the 2nd ed on Krzy's blog.
BTW: I used your DO, DON'T, CONSIDER idiom for an internal quality-and-guidance document at work, and my manager was blown away by it! So much so that he commissioned similar docs from other architects, and refers to them collectively as the DO, DON'T, CONSIDER documents!
Gee - I hope you didn't have that copyrighted... :)
The first edition is awesome! Every .NET developer should reserve a place for it in their bookshelf.
- I would like to some topics about documentation and especially xml documentation.
- I would like to see it to extend to internal/private code.
- Maybe include some kind of quick reference card with the most common standards/idioms.
- Complete book in searchable form (CD/PDF/.hlp) for quick finds when working in Visual Studio.
This is great news!!! I have used this book as a coding standard on all my projects since the release of the first edition. On several projects I have made the companies buy the first edition for every developer on my team.
I would like to see the patterns section expanded to include the not so common patterns use by the framework team.
I would like to see the book targeting TDD and Agile methodologies as developing frameworks has to be tested and confirmed to follow the design. And if this is how .NET framework or part of it was developed, would be a great asset to those who are building frameworks.
One of my favorite parts in the first edition were the little asides which explain certain design decisions made in the framework and how they came about or how you regret them.
It might be helpful to have little focus examples which focus on specific parts of the framework like "What is the correct way to implement/use feature X"
It's like a second Christmas in 2008!
I'd really like to see unit test design guidelines now that VS2008 has support built in. Unit tests are consistently something I find people aren't clear on how to write "properly."
If you can spend some time looking at logical const-ness and "programming in a functional style" that would be sweet.
Now, who do I have to sleep with to get an early draft? :-)
Please, please, get rid of the redundant "Do"s. When you have a page full of...
Do name widgets according to this guideline.
Do not name widgets in all caps.
Do keep all your widgets in line.
Do not sort widgets alphabetically.
...the do's and don't's all run together. Instead, keep the do not's but get rid of the entirely unnecessary do's:
Name widgets according to this guideline.
Keep all your widgets in line.
Let me second Keith Patrick's request; I would DEFINITELY love to see more XML Related documentation!
Architectural guidelines on WF and WCF / LINQ integration would be a compelling read
I'd like to see some sort of Icon in the margin (ala Code Complete) for the DO, DON'T and CONSIDER advice (rather than a tick or cross in the body of the text).
Also, how about more prescriptive best practices along the lines that the MS developers follow?
I also think that Unit testing/TDD guidelines would be very worthwhile (but not like the MSDN debacle!!!).
Alos, How about a condensed pull out card with all the most useful advice?
I'm interested to know whether this is a new EDITION, meaning that it contains everything still applicable from the first edition plus some more stuff, or a new VOLUME, meant to sit beside the first book. The article here uses both terms, but they are not really interchangeable, as they imply different things.
Thanks Mel... I fixed the issue. It is a new edition..
I have the first edition...its great, I found the rules and approaches valuable, but, where it helps developers of library APIs, it falls short on helping developers of applications. It would be great if the new edition could outline a standard approach to libraries that emerge out of code in a working application.
I agree with all the things listed above.
I also would like these things addressed.
What is the best way to implement a MVC? How to design a mixed solution with thick and thin client interfaces? How to manage and design Web services for change? It N-Tier dead?
How to best prepare your application for add-in developers.
How to best provide secure interfaces for external applications to extract data or invoke services from your app (like SAP).
When to choose generics over partial classes and standard inheritance.
What is LINQ? Why is it important? How should I prepare for it in my API?
While I enjoy the discussion between the different developers in the book about approaches to problems (and want them to stay) I'd like to see a prescriptive statement best practice. To the point where it takes to form "like this do that" The DOs DONTs and CONSIDERs get most of the way there but I want to say to my team "There! see! is says do it that way, so just do it that way! OK!". You guys may not realise how many arguments your book settles and therefore how much time it saves. :)
Couple other things that have been floated as coding guidelines but I've still got questions about:
1) Using namespaces: ages ago, I recall (I think it came from BradA) there was a guideline saying to put the "using" statements within the namespace declaration (only part of VS that I know of that does this automatically is usercontrols). I have yet to figure out why. What is the difference, and why does no one (I've never seen it done in the wild) do it per this guideline?
2) Naming of abstract classes: I've seen them named like regular classes, prefixed with "Base", and suffixed with "Base". What is the current naming guideline and why?
I would like to reiterate the request for guidelines regarding xml documentation. I found this blog post while searching for xml documentation guidelines, and I have been surprised at how little information is available, given how powerful and useful a feature it is.
This is my follow-up to Rodrigo's excellent post " How to be a better developer? ", where he
Please explain how to properly use LINQ in a typical 3-layered application architecture.
+1 for Kyralessa. It could/would be much easier to distinguish do's from don'ts (i.e. right from wrong).
It would be great to delve into design when using linq, not so much linq-sql but more linq-xml and linq-objects.
A lot of the projects I'm working on consume web service data (xml) and are using linq to create custom business objects to return to the client app. However there is no guidance on how to structure those methods, which parts of linq to use, which to avoid, how to handle deferred execution, particularly as it relates to exception handling & performance on objects and xml, whether to enumerate through the custom collection returned by linq before returning it to the client or let the client do the enumeration, what to base that decision on, etc. etc.
Basically we've found it hard to do any decent analysis and design decisions when using linq as there is so much that is deferred, "hidden" or not handled at the query level.