A Guide to SharePoint Naming Conventions

 

I am excited to see the great new site through the efforts of Jeremy Thake, Mark Miller, and  so many others.  They all did a great job bringing this together and I am happy to be asked to write an article for the new site.  My goal for today’s article is to provide some guidelines on establishing a set of naming conventions for your SharePoint environment.  This article has sections that apply to both end users and developers.  I am certainly not trying to tell you that you’re doing things the wrong way now and you need to redo things.  My aim is more to give you some ideas on how to find a set of conventions that works for your organization.   I’d love to hear your feedback in the comments and continue this with a follow-up article.

 

 

I’ve always had a love for establishing naming conventions and coding standards.  Just ask people that have worked with me. J  The theme, you will hear from m​e here today is that consistency is key.  This is rule #1.  What I mean by that is; I don’t think you should have the same thing called five different names depending on who wrote it.  For example, say you have a field called Product Code.  In an out of control environment, you might end up seeing this as ProductCode, ProductCd, ProdCode, ProdCd, ProductCde, ProdCde, txtPrdCd.  You get the idea right?  Guess which one I would pick?  You’ll be able to answer that question before you get to the end of the article.

Even if you aren’t a programmer, the ideas we use in naming things in programming also apply well to things in SharePoint.  Whether you are creating artifacts through the UI, a feature built in Visual Studio 2010 or SharePoint Designer 2010, you want great naming conventions in all places.  It makes it easier for your users to determine what you mean and it makes it easier for people coming along after you to choose names of their own artifacts.  The idea I present to you here today are not necessarily my own.  Many of them come from Patterns & Practices and what I have learned from people that are much smarter than me.

Rule #2.  Don’t abbreviate.  Seriously, don’t do it.  Is saving yourself typing a few characters really worth the inconsistency and ambiguity it creates? That’s why they created IntelliSense in Visual Studio any way.  Type a couple of characters and hit tab and call it good.  Of course not all of you are developers and IntelliSense only applies to code, but it really isn’t that big of a deal to type a few extra characters.  Now of course with every rule there are exceptions.  Sometimes it’s unavoidable.  Your company name may be too long that if you didn’t abbreviate it, you would exceed filename and path limitations.  This is a valid concern and we’ll talk about this limitation later when we talk about naming features.  The naming conventions and document agrees and says only abbreviate when it’s necessary and the acronym is well known (in your organization).  For example, many people know that NFL probably represents the National Football League, but what about BCS?  To a college sports fan, it probably means Bowl Championship Series, to a SharePoint person, it probably means Business Connectivity Services.  Now, don’t even get me started on BDC in SharePoint 2010.  That acronym got redefined and 7 out of 10 SharePoint people probably can’t tell you what it stands for now. (Totally made up factJ).  The point is abbreviation creates ambiguity.  Don’t make the people trying to figure out your work later have to guess what you mean.

Development

Ok, so by now, we know some basic best practices in naming.  End users forgive me for a bit longer as I am going to talk about naming Visual Studio projects and namespaces.  The reason I want to talk about this is the naming convention I prefer in Visual Studio also applies to SharePoint when it comes to features and solution packages.  I prefer to keep the names of the Visual Studio project, the assembly name, and the default namespace all the same.  Again, I’m keeping with my rule of consistency here.  Now, what do we choose for a name?  You have a lot of options here.  I try to follow P&P and choose a schema similar to what Microsoft uses.  It ends up being pretty verbose but there is generally no question what you are looking at.  Here is my first choice.

<Company>.<Project or Department>.<Technology>.<Optional subdivision>

Let’s look at a real example.  I work at Stonebridge (this is not a plug, it just makes for a good example) so let’s pretend I am working on some event receivers for our SharePoint site for the marketing department.  My namespace might look like this:

Stonebridge.Marketing.SharePoint.EventReceivers

If I had to build a Silverlight application for search, it might be something like this:

Stonebridge.Marketing.Silverlight.Search

I really like the dot notation here because it provides natural separation of each term.  Sure I could call my namespace something like StonebridgeMarketingSharePointEventReceivers, but that’s a bit harder to read.  However, I’m not one to judge, if that works for you, have at it.  I like the dot notation because it’s extremely versatile.  Going forward, I’ll demonstrate all namespaces prefixed by SomeCompany.

You might not want your company name in the namespace or maybe you want to use a product name in there instead.  As you know Microsoft follows a lot of these patterns as well.  Take the following examples:

SharePoint.Administration

Microsoft.Office.Server.Search

In the first example, the product is SharePoint, the company name is omitted, and we’re talking about classes related to SharePoint administration.  In the second example, the company name is used, followed by the product and lastly the type of classes.  Of course this scenario doesn’t follow our example because SharePoint is a platform and it makes sense to segment classes by product function.  If you are developing an internal framework library, I recommend you use this same approach though.  Again, I honestly don’t care what you implement as long as you are consistent.

Visual Studio Projects

Once you have a well-established namespace rule, it applies very well to what your name your projects inside Visual Studio.  There are a few things I do once I create a new project.  Depending on how you created your project and where you put it, you might want to rename the project file (the .csproj file itself).  I like to keep this the same as the default namespace for the project.  The next thing you want to do is change the default namespace and the name of the compiled assembly.  These will also share the name of the namespace. 

 
Here are some ample namespaces / projects that I typically end up using (again following the same naming schema from above):

Feature Name

Description

SomeCompany.Marketing.SharePoint

Deploys most SharePoint artifacts such as pages, content types, site columns, lists, etc.

SomeCompany.Marketing.SharePoint.EventReceivers

I always put event receivers in their own assembly

SomeCompany.Marketing.SharePoint.Workflow

Custom workflows or workflow activities

SomeCompany.Marketing.SharePoint.Data

Data access layer.  LINQ to SQL, Entity Framework classes, etc.

SomeCompany.Marketing.SharePoint.Business

Business logic layer

SomeCompany.Marketing.SharePoint.Services

WCF Service layer for interacting with my application

 

Now what you include in your projects is completely up to you.  My projects usually contain multiple items which span multiple sub-namespaces.  I do my best to keep the number of projects to a minimum because it makes things easier to deploy.  You can have as many or as few projects as you want.  Just keep in mind, the more you have, the longer it takes to compile and the more packages you have to install with PowerShell later when you go to production.

Solution Packages

I like to follow the same dot notation when it comes to the name of the solution package that gets deployed.  This means that the namespace, project name, assembly name, and package name are all the same.  Don’t you love the consistency here?  If I take one of the projects from above as an example, SomeCompany.Marketing.SharePoint, my solution package would have the filename, SomeCompany.Marketing.SharePoint.wsp.  When an administrator sees your package in the solution gallery later, this makes it easy for him or her to have an idea what your package does even if you didn’t provide a description.

Features

When it comes to features, I use the same techniques that I have been talking about to name namespaces and projects.  This makes it easy to identify who made the feature and what it does.  Here is an example.  How I do this differs slightly depending on whether or not I am using SharePoint 2007 or SharePoint 2010.  The reason for this is due to the way Visual Studio 2010 names the actual feature folder when it deploys it.  We’ll see this in just a minute, but first let’s look at 2007.

If you can remember back to SharePoint 2007 J, you might remember having a project structure set up something like what you see below mimicing the layout of the 12 hive.

When your solution package deployed your feature, you would end up with a folder in your FEATURES folder with the same name. 

 

This worked great with the dot notation that we adopted from above.  However, Visual Studio changes things just a little bit.  By now, you have probably heard about all of the great SharePoint Support in Visual Studio 2010.  When you add lists, content types, code, and other items to your SharePoint project it automatically creates features for you.  This is great, but we want to stick to some naming convention.  When a new feature is created, you will see it listed in your project as Feature1. 

 

The title of the feature is named ProjectName + Feature1.  In this case, the feature is named SomeCompany.Marketing.SharePoint Feature1.  Note, that a space is there between the project name and Feature1. 

 

Developers, please put a description on your feature.  It doesn’t have to be elaborate, just a quick sentence saying what it does.  Thanks. J

At this point, you want to rename the feature to something more meaningful as well as set the title.  To rename it, just right click on Feature1 and choose Rename.  For today’s example, I want to deploy content types.  Instead of specifying the full dot notation name, I just type in the end, in this case ContentTypes.  You will see why here in a second.  Here is what it looks like in Visual Studio.

I then edit the ContentTypes feature to update the title.  Here I specify the full dot notation as well as a description.


 When I deploy this, the actual folder that gets deployed is named with the name of the project itself and appends an underscore followed by the name of the feature.  In my example, Visual Studio would name the folder SomeCompany.Marketing.SharePoint_ContentTypes.  Now, you understand why we didn’t specify the dot notation here.  Visual Studio names your features this way to avoid conflicts between projects.  I don’t particularly like the underscore, but to my knowledge, there is little we can do about it.  I suspect if you wanted to write enough code, you could override this behavior though.

Viewing the feature in SharePoint, you will see the dot notation in the title and a nice description.

Any significant SharePoint project I am involved in I typically have the same set of SharePoint features.  I usually have ones to deploy content types, lists, event receivers, user controls, web parts, etc.  To generate the feature name, I simply start with the base namespace we came up with above and add to it.  Here is a table that demonstrates the idea.  Just keep in mind, in Visual Studio 2010; you’ll end up with an underscore in the name.

Feature Name

Description

SomeCompany.Marketing.SharePoint.ContentTypes

Deploys content types and site columns (I like to deploy them in the same feature)

SomeCompany.Marketing.SharePoint.Lists

Feature that deploys lists or document libraries.  Can deploy multiple lists.  If you want to separate things out, you could have a feature like SomeCompany.Marketing.SharePoint.Lists.SharedDocuments

SomeCompany.Marketing.SharePoint.EventReceivers

Installs the event receivers

SomeCompany.Marketing.SharePoint.Pages

Deploys pages using the module element

SomeCompany.Marketing.SharePoint.Workflow

Custom workflows or activities

SomeCompany.Marketing.SharePoint.Forms

InfoPath forms

 

Site Columns / List Columns

I promised you there was some end user content in this article and here it is.  Site Columns can be deployed by developers using Visual Studio or end users using the UI or both using SharePoint Designer.  We’ll look at it from the end user perspective first.  As an end user, you probably have no idea if you organization has any naming policy.  Maybe it has a governance policy but chances are you have never seen it.  I’m going to give you some recommendations that will make things easier on you and possibly your developers down the road.  Again, consistency is the goal.

When creating a site column, it is good if you have a little understanding of what is going on behind the scenes.  Internally, the site column has many different names that SharePoint keeps track of.  As an end user, all you ever see is the Display Name (DisplayName in the Field element).  However, developers care more about the internal name (Name in the Field element).  As an end user, did you know that you can control what the internal name is when you create the site column?  What happens is the name you specify in the Column Name field in the UI becomes the Display Name and the internal Name when you create the site column. 

Once the column is created, the internal name cannot be changed.  Why does this matter?  It matters because you want that internal name column to be named consistently with everything else.  How should you name it?  I would start by sticking with rule #2, do not abbreviate.  On top of that, don’t use spaces.  Developers hate spaces in site column names.  They will like you a lot more if you leave them out.  I would also leave out any special characters as well.  As example, I would use site column names such as these:

 

  • ​ProductCode
  • Color
  • SatisfactionRating

 

I know what you are thinking.  Those column names are ugly.  My users will be confused.  No problem.  Remember, I said the initial name you specify when creating the column sets the internal name and it cannot be changed.  Once you have created the column, just edit it again and change the name.  It will then just change the display name and leave the internal name intact.  Do this and you will have site columns that will make both your end users and developers happy.

Now as a developer, you should consider this as well.  If you are deploying site columns using CAML, you should set both the Name and DisplayName attributes.



 


 

 

 

 

If you like creating site columns with code, the second parameter of the SPField constructor is the internal name of the site column.  The Title property sets the Display Name.




 

 

 

 

Content Types

Content Types go hand in hand with Site Columns, so we follow the same rules.  Avoid abbreviation when naming your content types.  I still prefer to avoid spaces in content type names, but some people do like spaces here.  I’ll leave that up to you.

Lists

Choosing good names makes finding lists easier.  All of the other naming rules apply here, but you should decide on whether you like spaces or not.  SharePoint has no issues with you putting spaces in the name of a list or document library.  A lot of the default lists such as Shared Documents included in site definitions such as the Team Site have lists with spaces in them.  When a space is used in the URL, it gets converted to %20.  Your browser will let you type in the URL as a space or a %20 when you want to access that list.  I’m not really a fan though.  I think they are a pain so I tend to make lists without spaces just like how I make site columns without them.  Again, you can decide what is best for your organization. 

Sites

For sites, I recommend following the same guidelines you do with lists.  This simply allows the URLs of sites to be typed in easier.  You can make the title whatever you want, just be consistent in the way you set the URL for the site. 

Search

I would venture to guess that most companies don’t typically set a policy on what to name things in Enterprise Search, but since I’m so passionate about the topic, I’ll give you my opinion.  Of course, rules number 1 and 2 apply here.  We want consistency and we don’t want abbreviations.  End users don’t really ever see these settings, so it may not matter to you at all.  Content Sources are typically camel cased and contain spaces (i.e.: Local SharePoint Sites).  For managed properties, I recommend following the same naming conventions that you use for variables.  You want to avoid spaces as they get encoded as _x0020_.  End users often do see scope names throughout the SharePoint site on your master page or in the search center, so I do recommend naming these with human readable text.  That means, use words, case things appropriately, and do use spaces.  Some examples of scopes names would be Products, Accounting Documents, and All Sites.

To SP or not to SP?

If you look at the naming guidelines, there is a well-established set of guidelines on how to name namespaces, classes, and other public members.  Unfortunately, the SharePoint product team must have not gotten a copy of that document when they were designing the API. J Let me just go on public record that I absolutely hate the fact that nearly every class in the SharePoint API is prefixed with the letters SP.  In my opinion, this completely violates the guidelines set by Patterns & Practices years ago.  This is why I was so relieved to see that the SP prefix was dropped in the Client OM.  If it’s not clear at this point on whether or not I think you should prefix SharePoint artifacts, classes, or namespaces with the letters SP.  The answer to that is unequivocally no.  J

Variable Naming

All of the things we have discussed so far apply fairly well to variable naming as well.  When working with the SharePoint API, I have a few things I do when working with classes like SPSite or SPWeb.  As you probably know, SPSite refers to a site collection and SPWeb refers to a site.  It’s confusing I know, but unfortunately we are stuck with that from old versions of the SharePoint API.  Now, if you wanted to create an instance of an SPSite, what would you call it?  spsite?  currentSPSite?  I don’t like anything with SP in it of course.  In the case of SPSite, I usually go with just siteCollection or maybe currentSiteCollection.  If I am working with multiple SPSite objects, I might name it something like sourceSiteCollection.   What about SPWeb?  For that I just use site or currentSite.  This is just my preference, but it makes sense to me.

Ownership

If your organization decides to adopt a naming convention, you are going to need some means to enforce it in your organization.  If you’re not a manager, director, or enterprise architect, you may have trouble getting others to adopt your ideas.  This means you will likely need to convince your boss or your boss’s boss that the company can benefit from standardization.  This may be an uphill battle, but with the right amount of determination, hopefully you can get some buy in from your peers.  You’re not likely to get far if you don’t have some management support. 

Once you have naming guidelines in place, you will need to periodically review your code as well as items created in SharePoint.  This is the hard part.  It’s easy to create a guidelines document but if no one reads it or no one ever makes sure it is being followed, it doesn’t do you much good.  Just think of this as a subset of your governance policy.  You do have governance right?  That could be a whole other topic. J

Summary

I hope this serves as a good guide when it comes to naming your next great project, site column, form, etc. in SharePoint.  When trying to remember what to name things, just remember our two simple rules again.

 

  1. Be consistent
  2. Don’t abbreviate

 

If you only follow those two rules, you’ll already be in better shape than most people. Again, these are only suggestions and I won’t be offended if you don’t choose to follow them.  Do you have a way that you like to name things?  Great! Post a comment and tell us about it.  We’ll compile your ideas and add it to a follow-up article in the future. 

As for what I thought the field I mentioned at the beginning of the article should be called?  ProductCode of course, but I’m sure you already knew that by now.