.NET Naming Guidelines (C#)

[mrashidsaleem]

Can anyone guide me what is wrong with the naming conventions
suggested below? I know that this is not recommended by many
(including Microsoft) but I need to know what exactly is the rationale
behind going for a different convention in .NET. The recommendations
do make sense (to me, at least but I may be wrong and would like
someone to correct me).

Scope Prefixes
Member Variable Prefix: Most of the people still use (and like the
idea of) prefixing member variables. Selection of prefix still remains
debatable. A lot of people use underscore to declare a member
variable. Use "m" as it also matches the convention generally followed
in VC++. Use of "this." in the code everywhere where a member variable
is used is clearly an overhead and there have always been a high
percentage of developers who tend to omit this causing standard non-
compliance. Hence this is not recommended.

Parameters Prefix: Length of a vast majority of functions in code
could easily go beyond 70 lines. Normal editors, viewers and IDE
support a maximum of 35 lines viewable at one time (at a resolution
1024 x 768). As one scrolls through lines of code (e.g. when reviewing
the code), it is important to readily identify if the parameter is a
local variable or is being passed in the function from outside. Use a
parameter prefix (e.g. "r" for inputs, "p" for out, ref).
It is also important to note that developers do not ALWAYS use Visual
Studio IDE to view / modify code hence IntelliSense cannot be taken
for granted. Examples where the code is viewed / modified outside IDE
is checking code file differences with Visual Source Safe (or other
such tools), doing code reviews, checking code files on deployment
machines and modifying ASP.NET code-behind files on deployment
machines to provide quick fixes.

Hungarian Notation / Type Prefix: This is now regarded as a bad
practice by Microsoft and many others. The full Hungarian Notation
(with every type having a unique type prefix) is impractical anyway.
However "Light" Hungarian, i.e. the use of Hungarian Notation only for
primitive types (i.e. a limited list; not for all types) still helps
to identify if a particular variable is being used appropriately (by
identifying its data type from prefix) and to check boxing / un-boxing
of variables without going back & forth between variable declaration &
usage.

Constants (not readonly fields) should be all uppercase with
underscore as separator (matches the convention for VC++ and Win32).

[Mattias Sjögren]

>As one scrolls through lines of code (e.g. when reviewing
the code), it is important to readily identify if the parameter is a
local variable or is being passed in the function from outside.

It is? I can't say that it matters that often to me (unless it's an
output parameter).

>Use a parameter prefix (e.g. "r" for inputs, "p" for out, ref).

That's fine for private methods, but I wouldn't use it for publicly
accessible ones. Keep in mind that parameter names becomes part of
your public "interface" . Forcing your own naming conventions onto
consumers of your library isn't very nice.
Mattias

--
Mattias Sjögren [C# MVP] mattias @ mvps.org
http://www.msjogren.net/dotnet/ | http://www.dotnetinterop.com
Please reply only to the newsgroup.

[Jon Skeet [C# MVP]]

<mr***********@ hotmail.comwrot e:

Can anyone guide me what is wrong with the naming conventions
suggested below? I know that this is not recommended by many
(including Microsoft) but I need to know what exactly is the rationale
behind going for a different convention in .NET. The recommendations
do make sense (to me, at least but I may be wrong and would like
someone to correct me).

Scope Prefixes
Member Variable Prefix: Most of the people still use (and like the
idea of) prefixing member variables. Selection of prefix still remains
debatable. A lot of people use underscore to declare a member
variable. Use "m" as it also matches the convention generally followed
in VC++. Use of "this." in the code everywhere where a member variable
is used is clearly an overhead and there have always been a high
percentage of developers who tend to omit this causing standard non-
compliance. Hence this is not recommended.

I don't tend to care too much what people do with private variables -
it doesn't affect me.

Parameters Prefix: Length of a vast majority of functions in code
could easily go beyond 70 lines.

Not in my code. Any methods I have over a screenful will be refactored
where possible.

<snip>

Hungarian Notation / Type Prefix: This is now regarded as a bad
practice by Microsoft and many others. The full Hungarian Notation
(with every type having a unique type prefix) is impractical anyway.
However "Light" Hungarian, i.e. the use of Hungarian Notation only for
primitive types (i.e. a limited list; not for all types) still helps
to identify if a particular variable is being used appropriately (by
identifying its data type from prefix) and to check boxing / un-boxing
of variables without going back & forth between variable declaration &
usage.

Makes the code less "fluent" when reading it "aloud" (even mentally).

Constants (not readonly fields) should be all uppercase with
underscore as separator (matches the convention for VC++ and Win32).

Not nearly as easy to read as Pascal case.

--
Jon Skeet - <sk***@pobox.co m>
http://www.pobox.com/~skeet Blog: http://www.msmvps.com/jon.skeet
If replying to the group, please do not mail me too

[mrashidsaleem]

On Feb 27, 11:48 am, Mattias Sjögren <mattias.dont.w ant.s...@mvps.o rg>
wrote:
Thanks Mattias; would you like to comment on the other conventions
suggested (specially the one for member variables)?

That's fine for private methods, but I wouldn't use it for publicly
accessible ones. Keep in mind that parameter names becomes part of
your public "interface" . Forcing your own naming conventions onto
consumers of your library isn't very nice.

That's a very good point. However, with .NET, you are bound to
use .NET FCL. Does this mean that you should always follow the
conventions followed in the FCL? (I don't think otherwise there would
have been a universal coding conventions document for everyone working
with .NET Framework).

[Mattias Sjögren]

>Thanks Mattias; would you like to comment on the other conventions

>suggested (specially the one for member variables)?

Well I didn't intend to, since (just like Jon wrote) I don't really
care how people name their private members, as long as they are
consistent. Personally I use a _ prefix for fields, but I'm not saying
that's more correct than any of the other styles.

I've never really missed using Hungarian notation in C#. I don't agree
with your argument that it would help ensure proper use. I think the
compiler does a pretty good job with that anyway.

You also wrote

"Use of 'this.' in the code everywhere where a member variable
is used is clearly an overhead"

I hope you mean typing overhead when writing the code, because there's
certainly no runtime overhead if you chose to use 'this'.

>That's a very good point. However, with .NET, you are bound to
use .NET FCL. Does this mean that you should always follow the
conventions followed in the FCL? (I don't think otherwise there would
have been a universal coding conventions document for everyone working
with .NET Framework).

The .NET Framework design guidelines is as close as you get to a
"universal coding convention" to use for publicly accessible members.
But since many of the BCL classes were coded before or during these
guidelines were written, there are certainly violations in the BCL we
have to live with.
Mattias

--
Mattias Sjögren [C# MVP] mattias @ mvps.org
http://www.msjogren.net/dotnet/ | http://www.dotnetinterop.com
Please reply only to the newsgroup.

[Keith Patrick]

Scope Prefixes
Member Variable Prefix: Most of the people still use (and like the
idea of) prefixing member variables. Selection of prefix still remains
debatable. A lot of people use underscore to declare a member
variable. Use "m" as it also matches the convention generally followed
in VC++. Use of "this." in the code everywhere where a member variable
is used is clearly an overhead and there have always been a high
percentage of developers who tend to omit this causing standard non-
compliance. Hence this is not recommended.

I personally use the "_". It groups the fields in a completely different
section of the member dropdown, and is one less character than C++ (plus,
C++'s naming conventions are an awful starting point given how many prefixes
got put in there due to macros. Also, variable fields should never be
exposed publically anyway (I don't even expose them protected), and as
private members aren't subject to guidelines, you can really name them
whatever you want; I just use the _ + the property name, though. FWIW, I
also always use this. as well as class name for static props (so I can tell
quicker what I'm acting on)

>
Parameters Prefix: Length of a vast majority of functions in code
Hungarian Notation / Type Prefix: This is now regarded as a bad

The primary reasoning (IIRC) behind this is that the IDE should be telling
you what your parameters are rather than building it into the text of your
code. Back in the day, when you didn't have tooltips in your IDE, putting as
many queues as possible into the name itself as to what the var is and how
it is treated by the compiler. Now that the IDE has enough widgets to tell
you that in other ways, to put them in your code becomes superflous and
potentially confusing (we're getting close to a time when developers won't
know the difference between pFoo and lpFoo)

Constants (not readonly fields) should be all uppercase with
underscore as separator (matches the convention for VC++ and Win32).

It's an old convention and inconsistent with the casing standards (Pascal
for readibility and because Anders Heijsberg is da man). They now shoot for
readability and consistency, and having screaming text (the all caps)
changes the feel of the language.
Additionally, I cannot recommend enough Framework Design Guidelines (by
Krzysztof Cwalina and Brad Abrams). It's a collection of stuff like this
PLUS explanations as to why MS made the choices they did.

[Keith Patrick]

Now that I've got the Framework Guidelines in front of me, a few things:
1) they actually do say "DO NOT provide instance fields that are public or
protected." I'm actually a bit surprised, since MS itself uses protected
fields in the BCL, but it could be pre-guideline code (but not a given; even
3.0 breaks the IsX boolean convention)
2) Cwalina says the downsides to Hungarian notation are: "cost of
maintenance, confusion if maintenance was not done properly, and finally,
Hungarian makes the API more cryptic". He also seems to say that OO
encapsulation itself is making the need for knowledge of exact type (he also
shows up in the forums, so he can correct me if I'm wrong or incomplete).
Another annotator - Jeffrey Richter - brings up the tooltip point and goes
with using "m_" for private instance fields and "s_" for private static
fields, saying that it doesn't really matter since guidelines don't cover
private members; I don't use the m or s because I only differentiate between
static and instance during declaration/instantiation and referencing with
this. vs. MyType. This Richter guy gets an A+ in my book because he also
does not reference private fields outside the property; some developers will
use the field if possible for performance, but as he says, you aren't
protecting yourself from code (via property logic) like you do for external
usages.
3. Regarding all-caps, all that is said is "We used the term SCREAMING_CAPS
to indicate an all-uppercase style. Luckily this style (and name) did not
survive in the final guideline." I think the general annoyance people have
towards all-caps (try posting a Usenet post in all-caps to see :) ) is what
led to it being abandoned. I also tend to think that the general lack of
readibility that's developed in C++ over the years (Managed C++....wow)
meant that there would be a relatively clean break from C++ standards.

[mrashidsaleem]

Keith, Mattias; thank you very much for explaining the Pros & Cons of
different conventions in detail.
Although I had come across the guidelines before, I didn't really
understand the rationale as the MS Naming Guildelines documentation
tend to be very concise (specifies "Do this" and "Dont do that" and
doesn't explain why; sometimes leaving veteran C/C++ developers to
wonder why they have opted for something different in .NET).
Its clear to me now that the private (or member; members MUST always
be private as per guildelines) variable naming convention is up to a
development team to choose (should still be documented though!).
Anything exposed (public, protected) must (or should?) conform to the
MS Naming Guidelines.
I find FxCop to be a great tool to automate such things (I assume
that, since the tool runs on a compiled assembly file, it just checks
for exposed members and doesn't care about your private variables
conventions) hence could be an excellent choice if one chooses MS
Naming Guidelines.
Once again thanks a lot for the excellent explanations,
recommendations , guidelines etc. etc. ... :).

Keith Patrick wrote:

Now that I've got the Framework Guidelines in front of me, a few things:
1) they actually do say "DO NOT provide instance fields that are public or
protected." I'm actually a bit surprised, since MS itself uses protected
fields in the BCL, but it could be pre-guideline code (but not a given; even
3.0 breaks the IsX boolean convention)
2) Cwalina says the downsides to Hungarian notation are: "cost of
maintenance, confusion if maintenance was not done properly, and finally,
Hungarian makes the API more cryptic". He also seems to say that OO
encapsulation itself is making the need for knowledge of exact type (he also
shows up in the forums, so he can correct me if I'm wrong or incomplete).
Another annotator - Jeffrey Richter - brings up the tooltip point and goes
with using "m_" for private instance fields and "s_" for private static
fields, saying that it doesn't really matter since guidelines don't cover
private members; I don't use the m or s because I only differentiate between
static and instance during declaration/instantiation and referencing with
this. vs. MyType. This Richter guy gets an A+ in my book because he also
does not reference private fields outside the property; some developers will
use the field if possible for performance, but as he says, you aren't
protecting yourself from code (via property logic) like you do for external
usages.
3. Regarding all-caps, all that is said is "We used the term SCREAMING_CAPS
to indicate an all-uppercase style. Luckily this style (and name) did not
survive in the final guideline." I think the general annoyance people have
towards all-caps (try posting a Usenet post in all-caps to see :) ) is what
led to it being abandoned. I also tend to think that the general lack of
readibility that's developed in C++ over the years (Managed C++....wow)
meant that there would be a relatively clean break from C++ standards.

[mrashidsaleem]

"Use of 'this.' in the code everywhere where a member variable

is used is clearly an overhead"

I hope you mean typing overhead when writing the code, because there's
certainly no runtime overhead if you chose to use 'this'.

Sorry, I missed that in my earlier reply. Yes, I did mean typing
overhead. One of my goals is to be 100% compliant with whatever
standards we finalize and I do not want to put anything unnecessarily
in standards that stands JUST as an overhead for the (lazy! :))
developers to follow.