Why it is important?
Coding conventions serve the following purposes:
- They create a consistent look to the code, so that readers can focus on content, not layout.
- They enable readers to understand the code more quickly by making assumptions based on previous experience.
- They facilitate copying, changing, and maintaining the code.
- They demonstrate C# best practices.
Code style recommendations
| Entity | Pattern |
|---|
| Types and namespaces | UpperCamelCase |
| Interfaces | IUpperCamelCase |
| Type parameters | TUpperCamelCase |
| Methods, properties and events | UpperCamelCase |
| Local variables | lowerCamelCase |
| Local constants | lowerCamelCase |
| Parameters | lowerCamelCase |
| Fields (not private) | UpperCamelCase |
| Instance fields (private) | _lowerCamelCase |
| Static fields (private) | _lowerCamelCase |
| Constants fields (not private) | UpperCamelCase |
| Constants fields (private) | UpperCamelCase |
| Static read-only (not private) | UpperCamelCase |
| Static read-only (private) | UpperCamelCase |
| Enum members | UpperCamelCase |
| All other entities | UpperCamelCase |
Try to give names for entities without any abbreviations. Name should describe entity’s purposes.
Using statement
1. Please put “using statement” outside of namespace.
using System;
using System.Text;
using System.Web.Mvc;
namespace SampleProject.Controllers
{
}
2. System usings should be placed first, then all others
3. Usings should be sorted alphabetically.
Return statement
1. Please separate return statement from other code with single empty line.
public ActionResult DashBoard()
{
DoSomething();
return View();
}
Curved brackets
1. Curved brackets should be places for “foreach”, “if”, “for”, “while”, etc. all the time.
if (someVal)
{
DoSomething();
}
How to implement rules if you are at the beginning of the project?
We assume that all team members should follow the code guidelines without any exceptions. So, know we have to think how we can achieve that statement. In general, all the cases will lead you to the following two cases.
- Rely on people
- Rely on tools
What does it mean to “Rely on people”? By this phrase, we assume that all team members will be responsible for following code style rules. There are some procs and cons of this approach. Although it is easy to start using it, there are some disadvantages of such approach. Among them – additional time for code style review and non-strict control of following the rules by all team members.
In such situation, tools can help the team to follow code style guidelines. Therefore, in this article, we will look at StyleCop tool (
https://stylecop.codeplex.com/).
StyleCop
Installation
To install StyleCop on your machine you need to download installer from the
https://stylecop.codeplex.com/ and run. Alternatively, you can open “Extensions and Updates” window in Visual Studio and install any appropriate extension, e.g. “Visual StyleCop”.
Create settings file
To create StyleCop settings file just right click on project and select “StyleCop settings”.
Select rules you want to follow and click “Apply”. After that, Settings.StyleCop file will appear in project folder.To download settings file click on following link
Settings.StyleCop.
Enable StyleCop on build
1. Open NuGet Package Manager for project you would like to validate.
2. Search for “StyleCop.MSBuild” package and install it.
3. Create file with rules, which are acceptable for your team.
4. Import that file to the project.
5. Build the project. As the result, you will see warning in “Error List” window.
Just described behavior is kind of soft behavior, because code compiled and application would work. To fix such situation you can do following things:
- In project’s properties change “Treat warning as errors” property
- Install “StyleCop.Error.MSBuild” NuGet package
After implementation all the steps above, you can be sure that everyone will follow the code style rules.
How to start using styling rules if you already have “billion” files?
It is no secret that majority projects does not have styling standards and we have to live with it. Let’s think how we can improve such situation.
Assumptions:
- At the begging do not allow to fail build on style settings validation
- After some period build should fail on code styling issue
I would like to recommend following steps to rewrite all code according style standard:
- Create styling rules for your project and introduce Settings.StyleCop with them
- Install on each developer’s machine StyleCop or another appropriate tool
- Create milestones with percentage of cleaned files
- Ask developers to change code according style rules in files, which they working on during current iteration
- Allocate time for code style fixes as technical debt
- Track progress
- Start failing build on style issues
Approximate roadmap for code style changes
Step 1
The step's approximate time frame is 0 - 6 week. During step 1 team concentrates on following:
- All team members have installed StyleCop tool on their machines
- While working on some area teammates do code style refactoring
- While code review first step to run StyleCop against created rules
- Team will concentrate on “main” libraries
- Team will allocate time for style fixes as part of technical debt stories
Step 2
The step's approximate time frame is 6 - 12 week. During step 2 team concentrates on following:
- We will enable code style checks on build. “StyleCop.MSBuild” package will be installed to libraries we would like to validate
- Code style warnings will appear
- Steps 1, 2, 3, 5 from first row
- Libraries coverage increased
- We will track number of style warnings
Step 3
The step's approximate time frame is from 12 week. During step 3 team concentrates on following:
- Warnings replaced with build failures. By this moment, we assume that all files will have appropriate style.
- In project’s properties change “Treat warning as errors” property
- Install “StyleCop.Error.MSBuild” NuGet package
- Deprecate style review on code review sessions
FAQ
How to apply settings for solution?
It is easy when you have only one file with rules and all projects in solution have reference to that file. StyleCop allow us to do that. Put file with rules in the root folder of the project. Then add to each projects’ folder Settings.StyleCop file with following lines.
