Paulo Morgado : CodingConventions

StyleCop 4.3 Is Out

Paulo Morgado — Wed, 20 Aug 2008 23:36:21 GMT

The StyleCop team announced the release of a version 4.3 of the StyleCop tool. You can get it from here.

On this version there are some bug fixes, new rules and documentation.

Also in this version, the list of errors and warnings goes to the Errors List window like with the compilers. I whish that the errors and warnings would also be sent to the Output window.

SDK documentation on how to author custom rules and integrate the tool with custom build environments is expected soon.

Microsoft Source Analysis for C# (aka StyleCop)

Paulo Morgado — Wed, 04 Jun 2008 23:12:22 GMT

I’ve learned from a fellow GASPer of the release of Microsoft Source Analysis for C# (aka StyleCop).

It’s still a work in progress but it’s already very useful.

Naming Conventions For Unit Testing

Paulo Morgado — Sun, 27 Jan 2008 22:13:36 GMT

Reading Roy Osherove's post about naming conventions for unit testing I have to say that it all makes sense to me.

I just want to add that for property testing I use the corresponding method names: get_Property and set_Property.

Naming Convention Violation On The .NET BCL

Paulo Morgado — Wed, 20 Jun 2007 00:16:00 GMT

I wonder who is responsible for this:

public class Formatter
{
    // ...
 
    protected ObjectIDGenerator m_idGenerator;
 
 
protectedFormatterm_objectQueue; 
    // ...
 
}

Can you spot how many naming conventions were violated here?

My Naming Conventions For Localized Concepts In C#

Paulo Morgado — Thu, 24 May 2007 23:23:20 GMT

I'm Portuguese and most of the software I design and develop is about concepts in Portuguese. How should I name stuff?

If I'm talking about Conta or Cliente it's easy: Account and Customer. And what about concepts that aren't in English or for which a translation would be unrecognizable?

When I name stuff I try to make things easily recognizable for those who read it, and this brings us to a combination of both Portuguese and English.

When someone finds in the code or documentation ContaInválidaException (names are in Unicode, it's time to let go archaic prejudice - "conta invalida" means that the account is making something invalida and "conta inválida" means that the account is invalid) identifies immediately what it is. For a business person it's obvious that it's something about an invalid account and for a technology person it's obvious that it's some kind of exception.

My C# Naming Conventions For Partial Class Files

Paulo Morgado — Wed, 23 May 2007 23:29:32 GMT

Following up on a previous post, this time I'll give you my naming conventions for partial class files.

There are two main reasons for me to break a class definition into more than one file. The main one is when I have inner classes and the other is when the file is getting too big.

How should I name the files? The usual tendency is to use a “.” as separator. This looks nice until you came across something like this:

public class MyComponent
{
    private class Activation
    {
        // Class implementation.
    }
 
    private class Deployment
    {
        // Class implementation.
    }
 
    #region Event Handling
 
    // Event handling code.
 
    #endregion
}

If I would extract the inner classes and use the “.” as separator, I would end up with the following list of files:

MyComponent.Activation.cs
MyComponent.cs
MyComponent.Deployment.cs

And, what about the long event handling code? Should I do the same? If so, I will end up with the following list of files:

MyComponent.Activation.cs
MyComponent.cs
MyComponent.Deployment.cs
MyComponent.EventHandling.cs

This doesn’t look very nice, does it?

So, here is my proposal:

“-“ separator for code from the top class
“+” separator for inner classes

This way, I end up with the following list of files:

MyComponent.cs
MyComponent-EventHandling.cs
MyComponent+Activation.cs
MyComponent+Deployment.cs

And this looks a lot nicer.

Naming Conventions for C#

Paulo Morgado — Sun, 20 May 2007 22:28:43 GMT

I'm a firm supporter of coding conventions (at least of my coding conventions).

Software factories [^] [^] [^] and other code generation tools have been taking care of writing the tedious (and, sometimes, ugly) code but, at some point, some code must be written and read by human developers. That's why (in my opinion) the way the code is written is as much important as the language it is written in.

There are several resources about coding conventions for the .NET framework:

I haven't read Brad and Krzysztof's book (yet), but I've read MSDN Library's guidelines and Juval's document and watched Krzysztof's presentation.

I have to disagree with Microsoft's position about naming conventions of private members. In an enterprise as big as Microsoft projects start and end, people move between teams and every time someone changes team he/she is faced with the possibility of having to learn and adapt to a new set of naming conventions for private members.

IDesign goes one step further on defining naming conventions for private members. I just don't like the convention they used. What's the point of prefixing private member fields (not variables as in their document) with m_? What does it mean? Member? If it's not a local method variable or a method parameter it's a member.

Some just prefix with _. Once again, why? What does that mean?

The only reason I can find for this prefixing practice is lost in the old days of colorless IDEs, printers and books. With colorful IDEs like Visual Studio 2005 you just need to qualify instance member fields with the this (Me for Visual Basic) keyword and static (Shared in Visual Basic) member fields with (lacking of a better solution) the class name.

Lets pretend for a moment that I'm one of the prefixes. How would I do it?

i_camelCase for private instance members.
s_camelCase for private static members.
c_camelCase for private constants.

Why stop there? Let's also prefix method variables:

v_camelCase for method variables.

Now I'm on a roll. Let's prefix method parameters:

i_camelCase for input parameters.
o_camelCase for output parameters.
r_camelCase for by reference parameters.

The next step would be to go Hungarian and add type information to the names, right? No. Let's stop here and get in the right track.

My Naming Conventions for C#

I Find that keeping naming conventions as simple as possible is the best way use and validate them.

Pascal casing for any class/struct member (constants, fields, properties, methods, events) except for private fields.
Camel casing for private fields and method/property parameters and variables.
Prefix interface names with I (IAccountService).
Prefix type parameter names with T (TKey, TValue).
Suffix type with meaningful names for its purpose (AccountService, InvalidAccountException, MustVerifyAccountAttribute, FromAccountTextBox).
Method names must reflect what they are supposed to do. Methods always do something, so they must start with a verb. (GetAccountInformation, UploadFile)
Names must be descriptive. Abbreviations should not be used. Hungarian notation should not be used. Single name variables should not be used.
Language keywords should be used instead of type names (string instead of System.String, int instead of System.Int32, etc.).
Business relatad names should reflect business entities or actions, and in the business' language (GetContaFromDataBase, ContaInválidaException, ValidarContaAttribute).
Underscores should not be used. Camel casing should be used to separate words.
Acronyms should be treated as a single word. Just to be compliant with Microsoft, for acronyms with less than three letters, all letters should be upper case.