Coding standards. Why and how with C#

KinsonDigital — Fri, 04 Feb 2022 04:20:31 +0000

Sigh. Coding standards.

Ever have this experience?

After an interaction like that, you walk away feeling like this.

I'm sure everybody at one point in their coding career went through this when your PR was getting code reviewed.
What a shame!!

Coding standards? Uhhh...why? 🤔

I have had both good and bad experiences being on teams with and without coding standards. Unfortunately, this is a human problem, not a technical one; solving the human issue is WAY more complicated!

But it doesn't mean that using technology can't help improve things!!

To help eliminate the issues that come with the pull request and code review processes, we can use technology to help shift our minds away from the little things like bracing style or spacing around parentheses. We should concentrate on things that bring value, such as architecture and code comprehension. But why do these things manually when technology can do it for us? With the manual process out of the way, we can keep the focus on what matters most; producing value.

I love coding standards for this very reason. We're not trying to "force" people to code the way we do. We want to get the team on the same page so we can concentrate on more important things.

Remember, there is no "wrong" way to code; just different ways to code. It depends on a variety of things like: language, the purpose of the code and software, the people on the team, and more.

Can .NET do this with the associated tooling?

Different platforms, languages, and tech stacks have capabilities to enforce and standardize your codebases. Each has positives and negatives and their own quirks. Fortunately, Microsoft and the .NET stack and associated tooling such as Visual Studio and JetBrains Rider have fantastic capabilities to help with this kind of thing.

Uhhh...how? 🤔

It depends on what kind of tooling you use. No worries, it's easy to do.

In the .NET world, enforcing coding standards is done by using an .editorconfig file.

You're probably thinking, "what is an .editorconfig file"? It's simply a text file that uses syntax similar to an INI file.

An INI file is a configuration file for computer software that consists of plain text with a structure and syntax comprising key–value pairs organized in sections. The name of these configuration files comes from the filename extension INI, short for initialization, used in the MS-DOS operating system which popularized this method of software configuration. The format has become an informal standard in many contexts of configuration, but many applications on other operating systems use different file name extensions, such as conf and cfg.

View on Wikipedia>

Adding this file in your project will give instructions to the tooling on what to enforce, what not to enforce, and at what level to enforce it.

Let's go over how to add an .editorconfig file to a C# project in Visual Studio first. Don't worry,we'll cover JetBrains Rider afterward.

Adding an editor config file to a project using Visual Studio (2022)

Right-click the project you want to add the .editorconfig file to.
Choose the Add menu item.
In the sub-menu, click the New EditorConfig menu item.

If you want to see the contents of the editorconfig, open the file in VS Code or any text editor.

Ok, sweet! We have our .editorconfig file. But wait! It's pretty much empty! What the 🤬? What's goin' on here?

Let me explain.

The .editorconfig files are just text. There is only one rule with a comment at the top of the file. The .editorconfig UI is a new feature that was introduced in the past couple years. Even though the file is pretty much empty, the UI shows that there are many rules that aren't visible in the file. This is because a new .editorconfig file will use all of the default values for all of the rules. Once you change a rule value in the UI to something other than the default value, it will automatically insert that rule into the .editorconfig file. Basically, if the rule is not in the file, then it is using the default value and there is no need to have the rule in the file.

Setting rules using Visual Studio (2022)

When a quick action with a 💡icon shows on the left side, click the little down arrow to fly out a tiny menu.
Choose the Suppress or Configure issues item at the bottom to display another menu flyout
Choose the type of configuration you want to apply

That's it!! An entry for the configuration you have chosen will automatically be added to the .editorconfig file. Of course, you can always just add the setting manually as well.

Refer to the GIF 👇🏼 below to see it in action.

Adding an editor config file to a project using JetBrains Rider

Right-click the project you want to add the .editorconfig file to.
Choose the Add menu item.
In the sub-menu, click the New EditorConfig menu item.

Ok, sweet! We have our .editorconfig file. But wait! It's empty! Seriously? 🤦🏼‍♂️

It's ok. We can still setup the rules. 👇🏼

Setting rules using JetBrains Rider

TL;DR

JetBrains Rider rules can only be edited manually.

Long Explanation 🥱

JetBrains Rider support for .editorconfig files, analyzing code, and enforcing standards are top-notch. They support advanced use of the file format and let you mix Resharper, .NET specific standard rules, and StyleCop rules in the file. In my opinion, it is the best in the industry. But, as we know, every piece of software does things differently.

But the downside is that JetBrains Rider does not automatically insert the rules into the config file.

But don't worry. I have a feeling that this feature will be coming to Rider. It was recently added to Visual Studio.
However, for some reason, configuring rules using action lists adds the configuration to the .sln.DotSettings file, not the .editorconfig file. This is one of the ways that JetBrains Rider let's you share rules with the team by committing them to your Git repository.

That said, if somebody knows how to interactively setup rules in JetBrains Rider with the UI, let me know!!
I looked into the documentation and found this, but I couldn't find the settings on how to do it.

Let's show how to manually enter a single rule.👇🏼

Conclusion

Ok, let's be realistic here. Every project has its unique requirements, oddities, and edge cases. Because of these reasons, each project requires its own coding standards. This isn't a one-size-fits-all scenario.

I love having standards put into place because it brings my projects and me a great deal of value. More importantly, it brings value to my users! My open-source projects Velaptor and CASL require consistency and strictness due to their low-level nature. Using the tooling and .editorconfig files helps me achieve this.

Cheers!!

If you are interested in any of my projects and how I set up and use .editorconfig files and analyzers, check out my projects and list of resources below.

Resources

StyleCop Analyzers for the .NET Compiler Platform
Index of EditorConfig Properties
Overview of .NET source code analysis
MS Docs / EditorConfig
editorconfig.org
Editor Config Cheat Sheet
If your interested in the rules that I use for Velaptor and CASL, refer to the GISTS that I created. Use them in your projects and tweak as necessary!!
- Solution Level Config
- Unit Test Project Level Config

DEV Community: KinsonDigital