Designing .NET Class Libraries: Naming Conventions (January 26, 2005)
Posted: February 16, 2005
Please note: Portions of this transcript have been edited for clarity
Introduction
frankred [MS] (Moderator)::
Hello & welcome to today’s Designing .NET Class Libraries chat on Naming Conventions. The chat will begin in a few minutes, so get your questions ready!
BradA [MS] (Expert):
Hello! Welcome to the chat. I am a lead PM on the CLR team, and I presented the session we are discussing today. You can find recent musing from me at https://blogs.msdn.com/brada
Krzysztof Cwalina (Expert):
Hi, This is Krzysztof Cwalina. I am a Program Manager on the .NET Framework Team responsible for the .NET Design Guidelines. I am glad to see so many people have joined in. My blog is at https://blogs.msdn.com/kcwalina/
BradA [MS] (Expert):
Q: True or False : private or protected fields should start with an underscore?
A: Protected - false. Private, I officially don't care as it does not show up in the public Object Model.
Start of Chat
BradA [MS] (Expert):
Q: Will this chat cover more than what’s already to be found at this URL? https://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/cpconnamingguidelines.asp
A: Yes. The presentations covered more of the why behind those guidelines and were slightly updated. The chats are designed to give the community a chance to ask follow-up questions.
BradA [MS] (Expert):
Q: will there be information published on how to add custom rules to FxCop or to the code checker that will be part of the 2005 IDE?
A: Yes. We are working on that now, but the intent is to allow developers to write their own rules. FxCop today has a rules SDK, and that will continue to exist going forward.
BradA [MS] (Expert):
Q: Why do the C++ coders @ MS continue to supply sample code with "old-school" type prefixes on variables, while C#/VB.NET coders are encouraged to drop them? I liked the old way better, and found it made the code easier to follow on paper.
A: I only cover the public object model in this class. Naming for private variables and private methods etc. are not covered. I have my hands full getting consistency across the public OM ;-)
frankred [MS] (Moderator)::
Q: When naming a variable are we supposed to put what type of variable it is, like: b_Closed ?
A: No. Different programming languages use different terms to identify the fundamental managed types, so class library designers should avoid using language-specific terminology.
Instead, developers are encouraged to Use names that describe a type's meaning rather than names that describe the type. In the rare case that a parameter has no semantic meaning beyond its type, use a generic name.
BradA [MS] (Expert):
Q: Will the code generated by typed DataSet and other automated tools or Wizards become FxCop compliant?
A: Good question. I encourage you to give feedback to the VS\DataSet folks ;-) Seroiusly, I know they are aware of the issue and they intend to pass fxcop, but they will likely not get all the way there for .NET Framework 2.0
BradA [MS] (Expert):
Q: Hi all. Hi Brad. Experts: What was the reasoning to rething Hungarian, especially the "m_" notation. I'm glad its gone. I personally think there's no place for it in C# as there's no need to distinguish from class members and [non-existant] globals
A: Well, there are a couple of reasons. To me the most compelling reason is how far we have come with the IDE. For example VS can tell you the type of the variable just be hovering over it. You don't need that type information encoded in the name.
Krzysztof Cwalina (Expert):
Q: Am I correct that updates have been / are being made to the MS Coding guidelines? If so, is there a place where a person can go view the most up to date guidelines?
A: I am trying to post all (or almost all) updates to https://blogs.msdn.com/kcwalina. Also, Brad has posted some to his Blog. Also, we are planning to make some updates to the MSDN docs around the time Whidbey ships.
BradA [MS] (Expert):
Q: In the presentation Brad mentioned some internal coding guidelines. Will you ever offer these up for public consumption?
A: Even the internal naming guidelines are not great. We have not focused much on this. We have focused a lot on the publicly exposed object model. That said, I can look at getting what we do have out there.
Krzysztof Cwalina (Expert):
Q: What advice can you offer when the naming goes wrong? E.g. I see that UCOMIStream (and others) are being obsoleted in Whidbey and a new ComTypes namespace has been created containing IStream (and others) even though this creates compatability issues.
A: We don't recommend re-implementing APIs just because of naming consistency issues. It's just not worth it, both from the perspective of the API developer (two code bases, two APIs to test, etc.) and the API user (two API to understand).
Krzysztof Cwalina (Expert):
Q: Krzysztof: wrt to re-implementing APIs based on naming issues, can you expand on why it was acceptable to do this for the ComTypes example I mentioned?
A: As you probably noticed there are many types in the Framework that don't follow even the most basic naming conventions. This is a long story with several reasons for it but quickly (and simplifying) it was too late for some APIs to fix them by the time we had all the rules and FxCop in place. In V1 of the Framework it was mostly manual cleanup work (to get consistency) and we prioritize System namespaces higher than System.Runtime.InteropServices.ComTypes (for example).
BradA [MS] (Expert):
Q: Should we shorten object names to make the namespace cleaner, or be more declarative and give full length names?
A: Well, like most things in life there is a balance. I generally find that most folks from the C\C++ side of the world error on the side of TMA (too many abbreviations) ;-). So generally speaking, I encourage folks to be descriptive. We have auto completion in the IDEs to keep you from getting carpal tonal syndrome, but the descriptive names makes things easier to understand.
BradA [MS] (Expert):
Q: I think the coding guidelines should cover all implementation (and not just publicly exposed code). It's nice to look through others code and know that _xxx is a private data member
A: Thanks -- that is good feedback. KCWalina and I argue about that all the time. I think our priorities are right, but I can certainly see your point that getting more into the implementation details would help.
Krzysztof Cwalina (Expert):
Q: It was mentioned that FxCop checks for 'suggested' casing of some common compound words ("FileName" or "Filename")... where can we find the list of words and their suggested casing?
A: Unfortunately, the list is not published anywhere. We are still finalizing the list, plus the list can get very long, and so I am still considering various options of how to best publish it –an XML file? :-). Since, you asked, I will try to make it higher priority.
BradA [MS] (Expert):
Q: Does code generated by Microsoft tools (i.e VS.NET) apply to any formal rules?
A: They do try to follow the best practices in the Design Guidelines especially as they relate to public object models. We also ensure they pass the FxCop security rules. But I am not aware of the naming standards they follow. If you see issues there, please point them out to me and I'll see if I can get folks to address them. I know it is an interesting topic, those cases where VS is putting code into YOUR project.
BradA [MS] (Expert):
Q: You said several times that you're only interested in the public object model. Will there be any recommendations for internal OM in the near future? As for the public OM, it would save us time and money.
A: Well, I am hearing the feedback from this group pretty clearly that it is needed. Now I just need to find the time to do it!
BradA [MS] (Expert):
Q: Will FXCop (sorry, FxCop!) be integrated to run in the background. It's be nice when typing to have it warn about, for instance, a property that has a set but not a get
A: Good idea, I will pass that suggestion on to the FxCop team.
BradA [MS] (Expert):
Q: Thanks Brad. I've suggested several FX Cop ideas to the team, but have never received a reply.
A: Send me mail: brada@microsoft.com
frankred [MS] (Moderator):
Q: Even though you say you're interested only on the public side (for now), I'm sure you have rules covering private members. Would it be possible to make your internal rules available. They would serve as a good guideline. (I write coding standards.)
A: While the coding guidelines are focused primarily on public object models, meaning the rules should be applied to classes and class members that have visibility external to the assembly, you certainly could adopt & apply the design guidelines to classes and class members that are internal to an assembly as well.
BradA [MS] (Expert):
Q: Will Microsoft ship a set of FxCop rules that are to be considered "Microsoft Best Practice" even internally in Microsoft?
A: Before the end of the year a few of us spent a bunch of time coming up with a subset of the FxCop rules called the "FxCop minbar"... that is the set of FxCop rules we expect every bit of the .NET Framework and Windows Longhorn to pass. Of course we still run the full set of rules, but we found that it is helpful to get very hard core on a subset. This subset focuses on the public OM and security issues. If folks would find that interesting I can see about making the FxCop minbar list public.
BradA [MS] (Expert):
Q: The "FxCop minbar" would be very nice to see.
A: Cool. I'll look into it.
BradA [MS] (Expert):
Q: Where will you post the "FxCop minbar"?
A: I will at least link to it from my blog.
BradA [MS] (Expert):
Q: Some of the application blocks definitely report violations from FxCop.
A: Ahh, yes. There are two things here:
1. We need to fix some of those application blocks it’s just bugs
2. You should *NOT* fix every fxcop violation. Remember it is just a tool, it is wrong sometimes. It needs *you* to be smart enough to make a call. That is why the first fxcop feature we included was the "exclude list".
BradA [MS] (Expert):
Q: Bit of a Tfs question but, can you enforce a set of naming standards to be followed before work is allowed to be checked-in?
A: Yes you can! We are doing that now for .NET Framework and Longhorn. We did a lot of work to FxCop to make it work in the labs and in the dev process, but we are seeing it pay off now as we are having less "late-found" issues. Sounds like there is room for a whitepaper on the topic?
BradA [MS] (Expert):
Q: Brad, I would definitely be interested in the white paper for enforcing naming standards before code check-in.
A: OK. Let me see what I can do. Folks are pretty stressed locking down beta2 right now, so it may be a while. But I will follow up. Check out my blog for updates.
BradA [MS] (Expert):
Q: From what I can remember of the very early guidelines, they did apply to private implementation details. Has this changed?
A: Well, the internal guidelines I spoke about a while ago did come from the early days, but as long as I have been doing this we have been focusing on the public OM aspects.
Krzysztof Cwalina (Expert):
Q: Brad, I know I asked you this privately, but is there an official position from MS for what to do with public internal namespaces? I have a namespace that I do not want available to SDK docs, etc. Currently I put them under MyCompany.Internal.
A: Yes, .Internal is the right way to go. I would just be very careful with such APIs, i.e. I would not make any assumption about your customers not using these APIs. Basically, all you can hope for is that .Internal will discourage people from using it.
Krzysztof Cwalina (Expert):
Q: So, moving forward, you're set on instead of ?
A: Only for type parameters that can benefit from being descriptive instead of one letter-long. ... but yes.
Krzysztof Cwalina (Expert):
Q: But for things like List, it's gonna be List and so on? And everything is a judgement call then?
A: Yes, List will stay List. Same with Queue, Stack, etc. In general, wherever we have just one type parameter that is unconstrained, it seems like T works just fine.
Krzysztof Cwalina (Expert):
Q: I have to say the and such already seemed very clear. I have never understood why there is a debate on this one.
A: Yes. I agree. Most existing BCL APIs were pretty self explanatory with the old naming conventions. Maybe with the exception of Converter and EventHandler. But the whole discussion started because off some more advanced APIs (in Indigo) that were just simply cryptic with the old conventions. In addition, we have the longest thread ever on the MSDN product feedback center with lots of comments in favor of more descriptive parameter names.
Krzysztof Cwalina (Expert):
Q: What about Dictionary ?
A: It's renamed Dictionary, pronounced Dictionary :-). the pronunciation is my personal/informal convention :-)
BradA [MS] (Expert):
Q: Are there (will there) be any guidelines on XML naming? For instance, when to use attributes rather than nodes, and whether attributes/nodes should be camel-cased or pascal-cased?
A: Good question. We have been working with the Xml team on this, but I don't know right now. I can certainly see that it is needed.
BradA [MS] (Expert):
Q: Should namespaces be just long enough to avoid ambiguity in component identification, or should they follow internal organizational hierarchies no matter the overall length?
A: I really dislike following internal organizational hierarchies. If your company is anything like mine, re-organizations happen constantly. What seems like a reasonable name today will seem terribly obtuse and outdated tomorrow. Try to stick with meaningful technology names for namespaces. Describe what the technology does rather than who does it.
BradA [MS] (Expert):
Q: Can you shed any light on when visual studio 2005 will be done and out the door?
A: Sure. "as soon as it is ready". ;-) Seriously, the teams are pushing hard on beta2 now. When you get it you should let me know how far from done it is. I feel confident that we will get the thing out this year.
BradA [MS] (Expert):
Q: When will Visual Studio 2005 be ready? :)
A: We’re working hard on it now. Ii feel confident that it will be ready this year. Beta2 will be the big test. If you folks like beta2 and it’s stable, fast, etc. then we are all good.
BradA [MS] (Expert):
Q: I'm writing a book and one of the chapters is called '.NET lifestyle'. It details things like: coding guidelines, naming conventions, tools and things that differ between the .NET world and C++/Win32. Should I remove references to non-public naming conventions?
A: Congrats on the book! No. I think you should leave in private naming because your book is trying to get across something different than the design guidelines doc is. Our guidelines are specifically for framework developers, where the public OM is the most important thing.
Krzysztof Cwalina (Expert):
Q: I'm writing a book and 1 of the chapters is called '.NET lifestyle'. it details things like coding guidelines, naming conventions, tools, and things that differ between .NET world and C++/Win32. Should I remove references to non-public naming conventions?
A: I think consistency guidelines are extremely important; it's not something the MSDN guidelines chose to talk about (as it's extremely difficult to get any consensus). We kind of left it as an "up to your team" issue.
BradA [MS] (Expert):
Q: I'm glad there's a go-live license in B2. Will this mean proper support for systems written using B2?
A: Yes! I love the go-live license. we get the kind of real world feedback we need to push the product to final release.
BradA [MS] (Expert):
Q: Continuing on VS.NET generated code: There are places where it formats code like if (true) {
A: OK - send me a couple of examples in email and I will follow up. Thanks!
BradA [MS] (Expert):
Q: What are your thoughts on naming conventions that need to be used to distinguish the class variables, function local variables and method arguments?
A: Well, let me break that apart. By class variables, I assume you mean fields. Those should be private (use properties for public exposure to provide a level of abstraction). For function locals, those are by definition private. For method arguments, those need to be camelCased. For the privates, I have seen two patterns in the .NET Framework: one is leading underscore, and the other is this.Foo. Either works for me.
BradA [MS] (Expert):
Q: From poking around inside the .NET Framework assemblies, it seems that a LOT of Win32 methods are already prototyped in C# and being used. Why not expose them via a Microsoft.Win32.Native namespace or likewise?
A: Check them out at https://pinvoke.net. A guy on our team runs the site and he has gone through our source and put them all up there.
BradA [MS] (Expert):
Q: Any estimate on Visual Studio 2005 Beta 2?
A: Soon... soon... We are just fixing bugs.
BradA [MS] (Expert):
Q: Can you offer any advice/tips for discovering prior art in the fx when choosing names for custom class libraries?
A: I personally use three methods for this:
1). Ask people how stuff was done in different technologies, the folks that work with those technologies most usually have good insights you might miss with the other mechanisms I will suggest
2). Use reflector and another object model browser to search for common patterns
3). Reflection is your friend. I have written hundreds of little scripts to look for different patterns.
Krzysztof Cwalina (Expert):
Q: Can you offer any advice/tips for discovering prior art in the fx when choosing names for custom class libraries?
A: I know what you mean. I have to do it all the time when I design/write new guidelines. I use a combination of knowledge about the Framework, object model browsers, and a simple custom tool that we call Lister. It's just a command line tool that lists all types/members/etc. meeting some criteria. For example, I was recently working on a convention for names of binary operator overload parameters. So, I programmed Lister to show me all binary operators, and I could see that most of the Framework uses either x and y or 1 as 2.
BradA [MS] (Expert):
Q: What phase of Beta2 are you in now? Ask, Tell, Final TP?
A: We are in tell mode. That means that for every bug a dev fixes, she has to tell the triage committee (division-wide) why she is fixing it. What the scenario is, etc. The committee gets a chance to push back, etc. Next, we go to ask mode where the bar goes up -we have to ask first before we fix a bug.
frankred [MS] (Moderator)::
Q: This might be out of scope, but are there any major updates/enhancements to FxCop planned in the near future?
A: Great question. Unfortunately, I don't have an answer off the top of my head. But, I can definitely get you an answer if you're willing to provide me w/your email address. Otherwise, please join us for the FxCop chat on April.
Krzysztof Cwalina (Expert):
Q: Krzysztof, the biggest thing I can think of is that most of the FxCop rules apply to code that is declared private.
A: Yes. We did not say that all guidelines apply only to visible APIs. The visible API restriction only applies to naming conventions and some design guidelines. Security, correctness, etc. guidelines apply to all code in a reusable library.
BradA [MS] (Expert):
Q: Where do you draw the line between "Framework" and "base class library"? Who decides what new bits go where?
A: Yes. The .NET Framework is the overall name for the product. It includes stuff like ASP.NET, Window Forms, ADO.NET and Xml. The Base Class Library (BCL) is part of the .NET Framework. It is the common part that can be used by any of the above bits. Sometimes that is clear and sometimes it is not until after one of the other teams builds something that we realize it is general purpose.
Krzysztof Cwalina (Expert):
Q: Will Peter Golde's power collections end up as part of the framework?
A: Not directly, but they will definitely influence the BCL collections. In fact they already do. We made several changes to the BCL collections based on feedback from the project. The Power Collections project is a great tool for us to validate extensibility of the BCL collections.
BradA [MS] (Expert):
Q: Leading underscore for private members is commonly used. Why doesn't it build when used on protected members?
A: I don’t like the underscore on protected members because this is part of your public Object Model. Remember, on an unsealed class anyone can subclass you and call that method. I think it is worth drawing a dark line between protected and private.
BradA [MS] (Expert):
Q: How about enumerations? Should the name of the enumeration be PascalCased and the values in the domain of the enumeration be camelCased?
A: Nope. The enum members are really public static fields and as such they should be PascalCased.
JoeDu [MS] (Expert):
Q: Will there ever be stream operators in the Framework/BCL? Things like console >> @"Hello world"
A: This is really a language feature--the BCL has all of the functionality to make it happen. For example, managed C++ (I believe) wires up their cout operations to the Console stdout stream when doing >> redirection. I don't think that C# or VB would want to introduce this functionality in the future. I haven't heard of it at least.
Krzysztof Cwalina (Expert):
Q: Brad: wrt reflection scripts, perhaps you could post these on your blog? Krzysztof: is there any chance of "Lister" being published?
A: I will see what I can do about publishing Lister on GotDotNet. If I find some time to clean it up and publish it. I will post something to my blog.
BradA [MS] (Expert):
Q: Brad: wrt reflection scripts, perhaps you could post these on your blog? Krzysztof: is there any chance of "Lister" being published?
A: I think I would be embarrassed for you folks to read the kind of code I write for this kind of thing. They are hacky, one-off tools, and I’d hate for someone to follow them as a best practice.
JoeDu [MS] (Expert):
Q: What is the preferred way of naming a control? okButton or buttonOk? The latter sort of follows the button1, button2...pattern, the former the naming pattern for child classes (and is definitely appropriate for things like MainForm that inherits Form)
A: This is a tricky area, as a lot of developers tend to use hungarian-ish notation with controls. E.g. okButton, featureTabs, and so on. Unless you're exposing this through a reusable API, there isn't really good DG guidance here. I would suggest standardizing across your team.
BradA [MS] (Expert):
Q: Is there a formal difference at MS between "Framework" and "Library"?
A: Ahh - I love that question. Krzysztof and I talk about this all the time. Yes, a library is a late 80s early 90s concept of flat dll entry points whereas a framework is more of an extensible object oriented functionality intended for 3rd party developers to use.
Krzysztof Cwalina (Expert):
Q: Was Hungarian notation (WRT method parameters) punted due to a rigorous study of developer efficiency, or was it abandoned because of "improvements to the IDE", or some less tangible metric? I just had a quick look at your blog and couldn't find the answer.
A: This is what I recently wrote on this topic for the purpose of clarifying the justification in the guidelines: "As with most naming conventions, there have always been both positive and negative effects of using the Hungarian naming convention (and they still exist today). Positives include better readability (if used correctly). Negatives include cost of maintenance, confusion if maintenance was not done properly, and finally, Hungarian makes the API more cryptic (less approachable) to some developers. In the world of procedural languages (like C) and the separation of the System APIs for advanced developers from framework libraries for a much wider developer group, the positives seemed to be greater than the negatives. In today’s landscape with System API designed to be approachable to a broader range of developers, and with Object-Oriented languages, the tradeoff seem to be pulling in the other direction. OO encapsulation brings variable declaration and usage points closer together, ..."
BradA [MS] (Expert):
Q: I'm wondering if any work has been done on guidelines for "should something be done?" Properties like the Use IOCompletionPort example from "fixing a broken class" slide in the talk.
A: I am not sure I understand... what do you mean "should something be done?"... do you mean the method vs. property debate?
BradA [MS] (Expert):
Q: No, not method vs property. It's a property that acts as a flag for how the code should operate.
A: Ahh, yes. I think we have those in different parts of the Framework.. The key to those, is that they should be able to be set in any order. I could also see a need to factor those out to their own class instances of which you configure and then pass in.
frankred [MS] (Moderator)::
It looks like we're about out of time. I hope everyone had a good time and got answers to all of their questions. If you have more questions please visit the CLR team blogs https://msdn.microsoft.com/netframework/community/blogs/default.aspx section on the .NET Framework developer center. Please join us again next Wednesday for the next chat in the Designing .NET Class Libraries https://msdn.microsoft.com/netframework/programming/classlibraries/ series.
.gif)
Top of page