As promised earlier, you can now download the concept version of my new Coding Guidelines for C# 3.0 and C# 4.0 from a dedicated CodePlex site at www.csharpcodinguidelines.com. The list of changes is quite big, and includes new guidelines covering object-oriented design, design principles, C# 4.0 and the smells and heuristics from Robert C. Martin’s book Clean Code. I’ve also removed many guidelines that have become obsolete or deal with situations that rarely occur. And the entire document has become much easier to read because I’ve changed to a less formal writing style.
A common question I receive regularly is how to introduce coding guidelines or coding standards into a team or organization, so I’ve adapted my April post on Coding Guidelines and included it into the document. Another question I get asked commonly is what to do if something is not covered by the document. For this, I’ve included my most favorite design principles that should help you determine when something is valid or not.
Similarly to the quick reference guide for the C# 3.0 version of the document, I’ve included a two-page A4-sized cheat sheet with the most important guidelines and some handy tables on naming, ordering and layout.
And finally, Jonne Kats and I started creating a set of FxCop and StyleCop rules that verify your code against some of the guidelines in this document. It’s a side project, so it may take a while before a first release will be made available. In the mean time, check out the source code repository regularly.
And last but not least, this document has not been cut in stone. So if you have remarks, comments, additions or complaints, just let me know. I’ve already received valuable feedback from the community and will continue to update the document whenever something useful comes to my attention.
3 comments:
A recommendable resource! Very thought-provoking, even embarrassing at times... To add one of my thoughts: I could'nt agree more with AV1076 (Evaluate the result of a LINQ expression before returning it) to avoid the pitfalls of deferred execution. However, to make clear that my method returns an evaluated list I tend to return a List in stead of IEnumerable, so a consumer of the method knows that evaluating the result is not necessary. But then there is the other useful guideline, AV1025 (Return an IEnumerable or ICollection instead of a concrete collection class). To me, methods returning IEnumerable, in contrast to Lists or Arrays, convey the message that execution is deferred (as most LINQ methods do): "I just offer an enumerator, you enumerate it whenever you want". So unconsciously I made my own guideline: use IEnumerable as return type to communicate that execution may be deferred. What do you (and others) think?
Thanks Gert. I really appreciate that.
For the record, I disagree with your approach. The fact that a method or property returns an IEnumerable simply indicates that the receiver will get some kind of collection, and that it should not make any assumptions about the actual collection class.
I would never return a IQueryable as an IEnumerable. I have seen some horrible bugs because the caller wasn't aware that its evaluation was deferred. If the caller is supposed to tweak the query somehow, I make it explicit by returning an IQueryable.
Fair enough. I agree on your distinction between IEnumerable and IQueryable. For the rest maybe it's just a matter of scope. As far as let's say internal methods are concerned (domain classes and domain services) I like the approach "return what you create", just to remind me where execution is deferred and where it isn't. Methods exposed in service boundaries, facades, and the like are a different story, though. There I tend to return the least explicit type, which in most cases would be an interface, as your guideline (1025) suggests.
Post a Comment