After thinking about my last post about that topic, I thought some additional information for people wondering about where to start with coding conventions might be prudent:
- ANY coding convention will be better than NO coding convention.
- If you have no convention in place, MSDN provides a good starting point: “NET Framework General Reference — Design Guidelines for Class Library Developers“.
- An alternative or extension may be the following download.
If you followed conventions implied in existing classes and code but have never read a formalized document, I recommend doing it. You may find same clarification (as the people at Microsoft did no allways follow their own conventions), so reading MSDN might be enlighting.
People who change projects or customers regularly should ask for the coding conventions when beginning to work in a new project. This will save you from later trouble. And in case there is none, that might tell you something about the state of the project.
At SDX we built our set of conventions upon the MSDN guidenlines (apart from saving effort, this avoids unnecessary discussions) and added conventions regarding file and directory structures, commenting, and other things. We complemented this with similar conventions for XML, guidelines regarding project setup (tool set, source code control, automated testing, …), and delivery templates (project document, installation document, …).
One major intention we had in mind was: All this is meant to guide and assist the developers, to help them doing their day-to-day work. We did not want to create a bureaucracy that gets in the way of the developer and creates additional burden.
A little bit beyond simple coding conventions, yet a usefull addition is “Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries“.
Another book that covers coding style and quite a few other topics (and is one of my all-time-favourites — I own the first edition published ’93): “Code Complete“, Steve McConnell.
And finally assaf‘s comment on another post deserves to be repeated: http://thedailywtf.com/Articles/Little_Black_Book.aspx 😉
That’s all for now folks,
AJ.NET
AJ's blog 
I really hate Hungarian naming for variables. esp in visual studio you don’t need them and they make extra work of reading each word when my eyes scan the line of text.
my teacher still uses it though – but i just can’t bring my self to write
“gpbNames”
when i could write
“NamesGroupBox”
i’ve heard that microsoft strongly discourages hungarian naming in visual studio and .net in general. is that correct?
Comment by hobbylobby — January 20, 2007 @ 11:57 pm
Short answer: Yes.
Longer answer: MS used Hungarian Notation heavily in C++ based frameworks like MFC and ATL. It made (and still makes!) sense to express type interpretation beyond the language type system, e.g. 0-terminated strings, or to denote type modifiers.
However those reasons do not apply in .NET. And even if, Hungarian Notation would have introduced a language specific convention in .NET. So MS dropped it.
Consequently MSDN states clearly “Do not use Hungarian notation.” (http://msdn2.microsoft.com/en-us/library/ms229045.aspx)
PS: To be frank, in the case of UI elements I still find Hungarian Notation usefull. I like lblFirstName + tbFirstName + … better than FirstNameTextBox + FirstNameLabel + … .
AJ.NET
Comment by ajdotnet — January 21, 2007 @ 2:22 pm
@AJ: I’m glad you added the PS there at the end, as it seems many (if not most) of us are still using Hungarian Notation for UI controls. I can’t find the reference at the moment, but I thought the design guidelines also indicated that firstNameTextBox would be just as incorrect as txtFirstName as you are still “unnecessarily” including the type in the variable name. This always seemed conflicting to me as you would often have a string firstName member on a form as well, so what the heck are you supposed to name the textbox that displays the same data?
Comment by cactus — February 9, 2007 @ 5:28 pm
I also see the same sort of conflict in the naming of fields and properties, where you aren’t supposed to prefix member fields with “m_” or “_”, but are not supposed to differentiate using case. How else are you supposed to deal with the simple situation of:
string firstName
public string FirstName {
…
}
Comment by cactus — February 9, 2007 @ 5:39 pm
I believe that underscores are a good way to differentiate private class membersfrom their public property counterparts. Its not discouraged by Microsoft, and in fact, they appear to use the “m_” prefix for the private members. Case can’t be an option in VB.Net, so to keep things consistent across both languages (my work uses VB – I use C#), I think underscore prefixes are perfectly fine. Any takers?
See this:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/cpconpropertyusageguidelines.asp
Comment by Brian — February 9, 2007 @ 7:07 pm
I would strongly recommend to use underscores to mark data members as such. Otherwise one would surely confuse them with method parameters and local valiables. The usage of “m_” is probably an MFC relict.
Comment by ajdotnet — February 9, 2007 @ 10:06 pm
I see that the comments stopped a while back, but I wanted to re-comment all the same.
I use underscores for private fields.
I like the underscore a lot:
it groups well in intelisense,
it doesn’t get in the way of reading the field name visually,
and it distinguishes the private name from the public property.
and i do use the following hungarian prefixes regurally: txt, lbl, btn.
i could easily give up the lbl as i rarely ever refer to labels within code… and i generally only name labels unless i know that i’m going to refer to them in code. and the ONLY reason I use any of the other prefixes is to group in intelisense… which i wish i could/would stop doing.
funny that AJ uses “tbFirstName” I saw that and wasn’t sure what it was referring to until he clarified that it was a textbox. that’s a funny thing about standards. in my first programming course, the teacher gave us a list of “standard” naming prefixes… the book’s code (in the book) was completely different… often using 2-char prefixes which it had said not to do. and the book’s digital code was yet again another version.
in the end, we had (an example)
for boolean: b, bl, bln, boo, bol
for dropDownLists: ddl, dd, cmbo, cbo, cbx
that’s just insane.
I’m lead on a project now and about to introduce another guy to the code (he’s been working with VB6 for years and loves throwing as many unspeakable consonants to prefix variable names) so i’m a bit nervous about getting him to convert to my standards and discard his old habits.
any suggestions on that one?
btw, thanks for digging up the ms naming conventions link.
Comment by hobbylobby — August 18, 2007 @ 1:28 pm
Your comment about ‘tb’ for TextBox rather than ‘txt’ implies an addendum to “ANY convention is better than no convention.” That addendum would probably be “MIXED conventions are worse.”
You took a very good point and it gives a crucial hint for the last issue. You should certainly agree on ONE convention. I would not automatically assume that is has to be _your_ convention, but your comment suggests that the other guy does not exacly provide a feasible alternative.
So everything boils down to the question: How do I ensure _consistent_ conventions in a project?
Best solution: Convince the other guy, persuade him to follow the convention. Every coding convention document should start with an introduction listing the reasons. Old habbits die hard but if he’s willing you won’t have to fight over it. Just a code review and a reminder now and then.
Worst solution: Make it an order (if you’re in the position to do that). This is sure to poison the working atmosphere somewhat but it may be the only way. It will probably require constant code reviews and harsh reminders. NOT recommended!
Somewhere in-between: State the conventions as fact, and use FxCop/code analysis/’warnings as errors’ to make it hard not to follow the conventions.
Not to be forgotten: Coding conventions are meant to help. But if people cannot agree on them you might be better off forgetting about them rather than causing constant trouble in your team.
HIH,
Alexander
Comment by ajdotnet — August 18, 2007 @ 2:53 pm
I admit it; when I said, “I’m a bit nervous about getting him to convert to my standards” I just meant wanting him to do it my way.
I honestly don’t think that’s a terrible thing though. My code is easier to read because I take great pains to make it as self-documenting as possible. i name variables carefully. i use enumerations as often as possible. i comment throughly. and I put in the extra effort to format each block in a presentable, structured way. –ofter rewriting or refactoring just to get a simple look to a given block. (however, I’m not perfect… error messages and dialog boxes always wrap and look terrible at some point.)
you have some good advice Alexander.
I think things will go smoothly and he’ll probably like my reasons for these kinds of things.
I do have the final say on things… but I’m not sure that I want to make it a battle of egos 🙂
I’ll try to convince him and try to use humor later on if his code is a mess. 🙂
now I’m wondering how far the average team leader goes when detailing to other coders about expectations, etc?
oh, I’m not familiar with “FxCop/code analysis/’warnings as errors’”. what is that?
Comment by hobbylobby — August 18, 2007 @ 10:03 pm
FxCop (http://www.gotdotnet.com/Team/FxCop/) is a tool that does static code analysis. It checks naming conventions, pattern implementation (such as the IDisposable pattern) and a bunch of other things. It also supports an SDK to build your own rules.
Code Analysis is simply FxCop introduced in Visual Studio 2005 (see project properties/code analysis). It’s 98% identical with FxCop.
FxCop and CA can be included in the build process and will issue warnings as necessary. With project properties/build, ‘Treat warnings as errors’ you can enforce a clean build, including the FxCop/CA rules.
Comment by ajdotnet — August 18, 2007 @ 10:51 pm
thanks for the details on code analysis. I’ll look into it.
🙂
Comment by hobbylobby — August 19, 2007 @ 4:54 pm
[…] ebook c#.net download (search.yahoo.com) [Referral] aspx coding (search.yahoo.com) [Referral] 84 (ajdotnet.wordpress.com) [Referral] http://www.dotnetkicks.com/page/6 [Referral] […]
Pingback by Gratis Buku C# - Free Download C# Book « — August 27, 2008 @ 7:57 pm