De gustibus non est disputandum.
- A Latin proverb, roughly "don't argue about matters of taste"
As Scott Guthrie noted here:, Juval Lowry has published his C# code layout standards here: IDesign C# Coding standards This compliments the classic: www.tiobe.com/www.tiobe.com/www.tiobe.com/standards/gemrcsharpcs.pdf
Low-level Code standards are wonderful things for your emotions– you can agree fervently with 90% of one, and recoil in disgust at the last 10%.
I'm going through Juval Lowry's document, and comment on the bits that I disagree with or want to explicate, and try to give reasons why I disagree. I'll try to be mindful that arguing that "It looks bad to me" is not a valid reason – what looks right to you is just what you're used to.
Point 9a: "avoid single character variable names" as noted somewhere in Code Complete, the comprehensibility of a short variable name is dependant on how wide its scope is. If the variable is referenced throughout the application, give it a long descriptive name. If it is used only over 2-3 lines of private code, a short or general name will suffice, and anyone can read a variable called "i" over this scope.. However, "loopIndex" is a short enough, general enough name for me to write.
Point 11: use capital letters for types. I find class MyDictionary<Key, Value> more readable than class MyDictionary<K, V> , and it's more in keeping with point 9.
Point 14: Put using statments outside the namespace. Howard van Rooijen pointed out to me that putting the "using" inside the namespace means that it applies to the end of the namespace, not the end of the file, and this is generally what you intend, so there is a case to be made that the "using" goes inside the namespace. I'm not entirely convinced: if this distinction is meaningful to you because you have multiple namespaces in the file, one after the other, then you're doing it wrong. Very wrong.
Point 20: Preface private members with "m_". Is this looking Hungarian? Maybe, but it may be better than the alternatives. Various other conventions on this are in use. Starting with an underscore is not CLS compliant in cases where the var becomes protected and could be called from VB.NET code. I dislike using no prefix at all, just lower case, since it ends up in constructors like this:
class Foo
{
private int bar;
public Foo(int bar)
{
this.bar = bar;
}
}
Which is just an accident waiting to happen in the constructor – two identically named variables are in scope, and the use of "this." To distinguish between them is not optional.
Point 24: Open curly braces on new line: There is an exception for the simplest of properties,
I.e.
public int foo
{
get { return m_foo; }
set { m_foo = value; }
}
More complex properties should not do this.
Point 25-26 -27
Now we are getting into real matters of taste. See the way that the code on trailing lines lines up with the right-hand of the equals stuff? I don't like that. I prefer to always indent trailing lines by one indentation stop (typically four spaces).
E.g. Not
int someReturnValue = CallAFunction(param1, param2,
param3, param4);
But
int someReturnValue = CallAFunction(param1, param2,
param3, param4);
Despite taste, there are advantages of this layout:
Indentation of the trailing line is consistent with other indented lines.
Indentation does not depend of the contents of the line above.
Indentation does not need to change if the line above changes, e.g. renaming the var.
Indentation is less, and thus there is more room on the line – the code is more readable as it's not all squashed up on the right.
Section 2
Point 12-13 Bill Wagner explained the difference between readonly and const – (Effective C#, Bill Wagner, Item 2) – essentially const is folded in at compile-time, readonly values can be updated by updating the assembly that contains it.
Point 26 Avoid explicit values for enums. Why not give values to enums? I would, when they have to be explicitly the same as ints stored on a database. Also if you don't specify values, the first one will be zero. Zero is best reserved for an "unknown"/"not set" value. (Bill Wagner - item 8). By saying "except when they are integer powers of 2" does not encourage the reader to be mindful that enums in C# (and C) play two slightly different roles - select one from a named, restricted set of values, and to provide a set of flags over those values (this is when the numbers must correspond to the powers of 2).
Point 55 – Why prefer String.Empty over ""? I had to find out why this one is correct. Because it doesn't create a new string instance each time. Apparently it's a trivial difference, but a difference nonetheless.
http://blogs.msdn.com/brada/archive/2003/04/22/49997.aspx
Point 56 – When is StringBuilder faster than concatenation? If there's a loop over lots of strings it is faster, but not if just concatenating three or four strings.
http://www.heikniemi.net/hc/archives/000124.html
http://www.chinhdo.com/chinh/blog/20070224/stringbuilder-is-not-always-faster/
http://www.chinhdo.com/chinh/blog/20070929/stringbuilder-part-2/