Welcome to another installment in the “CodeIt.Rules Explained” series. Not familiar with the series? Or maybe even with CodeIt.Right itself? Don’t worry, we’ve got your back.
CodeIt.Right?is a static analyzer tool. More specifically, it’s an automated code review tool and a really awesome one at that. CodeIt.Right works by checking your source code against a collection of rules, giving you instant feedback about its quality, and even offering automatic corrections to many of the issues.
We usually start out these posts with our rule of thumb for deciding whether or not to ignore a suggested fix:
- Never implement a suggested fix without knowing what makes it a fix.
- Never ignore a suggested fix without understanding what makes it a fix.
I won’t mind if you think I’m trying to be funny by wording it that way. But I assure you that’s not the case. I really believe it makes a difference when you put it that way, as two different sentences. This is by design. It’s meant to emphasize the choice you have in front of you: ignore the suggested fix or implement it. If you decide to ignore it, do so only when you’re completely aware of the risks.
The same thinking applies if you decide to go for it. By all means, accept a suggested fix if you feel like it, but do so only when you’re completely aware of the benefits it’s going to generate.
Mark Assemblies With Assembly Version
The first rule we’re addressing in today’s post falls into the “design” category.? CodeIt.Right is nagging you not to forget to put the assembly version?in the AssemblyInfo.cs file.
We talked about?what assembly attributes are?on this very blog not that long ago, in part 17 of this series. In short, assembly attributes allow you to manipulate metadata in the DLL’s and executables you ship when deploying your code.?These attributes include, for instance, the application name, the company name, and trademark and copyright information.
And how do you actually work with assembly attributes? You do that by editing the AssemblyInfo file, which you get for free whenever you create a project. Here’s an example of such a file:
Take a look at the last two attributes. They are, respectively, AssemblyVersion and AssemblyFileVersion. That can raise a few questions:
- What is the difference between those two?
- Which one of them does CodeIt.Right want me to fill?
- And why is this important?
OK, let’s tackle each question, one by one. What is the difference between AssemblyVersion and AssemblyFileVersion?
AssemblyVersion is the version other assemblies will look for when referencing your assembly. The logical consequence is that other assemblies must update their references whenever this value changes. AssemblyFileVersion, on the other hand, is something more “external,” if you will. It’s used for deployment. For instance, that’s what Windows shows you when you right-click the executable or DLL of your application and go to see its properties.
As it turns out, AssemblyFileVersion is optional. If it’s not informed, then the value of AssemblyVersion is used instead. How do you fix this violation? It’s very easy. You just add (or uncomment) the AssemblyVersion attribute, informing a proper version number like in the example below:
[assembly: AssemblyVersion(“1.2.0.0”)]
Each one of the values refers, respectively, to the following:
- Major Version
- Minor Version
- Revision
- Build
Revision and Build are optional, so the following example is also valid:
[assembly: AssemblyVersion(“1.2.*”)]
Do Not Use Deprecated Properties of Response Object
This rule falls into the ASP.NET category. It has to do with the?System.Web.HttpResponse class, which is used to encapsulate HttpResponse information from an ASP.NET operation. So what about it?
The HttpResponse class has four properties that were deprecated in favor of properties on other classes. When some method, property, class, or any source code artifact really, is deprecated, that’s a sign they might be removed on some future release of whatever software you’re using.
In the case of a development framework, such as .NET, removal would be a breaking change. The clients who made extensive use of the removed features could face a herculean task in order to fix the mayhem caused by this change in their application.
So when some software vendor (or even the maintainer of an open source project) declares some of their stuff as deprecated, they’re really giving you a heads-up or a gentle reminder that those artifacts probably won’t be around for long and you should be aware and take action.
What all of that means is that, with this rule, CodeIt.Right is warning you to make your code “future-proof” by not using deprecated stuff. So, without further ado, what follows are the deprecated properties of the HttpResponse class and what you should use instead:
- System.Web.HttpResponse.CacheControl—instead, use methods of the System.Web.HttpCachePolicy class.
- System.Web.HttpResponse.Expires—in its place, use methods of the System.Web.HttpCachePolicy class.
- System.Web.HttpResponse.ExpiresAbsolute—use methods of the System.Web.HttpCachePolicy class instead.
- System.Web.HttpResponse.Buffer—instead of it, use the System.Web.HttpResponse.BufferOutput property.
That’s all there is to it. Use the indicated methods and properties and you’re good to go.
Attribute Class Name Must Have “Attribute” Suffix
The third and last rule we’re covering today falls into the “naming” category. Here, CodeIt.Right is telling us that an attribute class must end with “attribute.” Well, that sounds reasonable if you know what an attribute class is. If that isn’t true in your case, you might be wondering what these things are and why that matters.
So first things first. What’s an attribute? In C#/.NET, an attribute is a way of adding metadata to a piece of code. In other words, it’s a mechanism that allows you to say things about your code. The attributes themselves don’t do anything. What happens instead is that they are read and analyzed by other parts of the code, which then use that knowledge to make decisions.
For instance, when writing unit tests, you’ll usually use attributes as a mechanism to declare that a given method is a test method, as you can see in the example below:
class StringCalculatorTest
{
[Test]
public void Add_EmptyString_ReturnsZero()
{
// arrange
string value = string.Empty;
StringCalculator sut = new StringCalculator();
int expected = 0;
// act
int actual = sut.Add(value);
// assert
Assert.AreEqual(expected, actual);
}
[TestCase("5", 5)]
[TestCase("1", 1)]
[TestCase("10", 10)]
[TestCase("7", 7)]
public void Add_StringWithOneNumber_ReturnsTheNumber(string value, int expected)
{
// arrange
StringCalculator sut = new StringCalculator();
// act
int actual = sut.Add(valor);
// assert
Assert.AreEqual(expected, actual);
}
}
When you run the tests, the test runner will look for methods with the expected attribute and run them. Attributes also come in handy in a lot of different situations, such as model validation in ASP.NET MVC.
Things wouldn’t be complete if you weren’t able to declare your own custom attributes. Doing so is actually quite easy.
[AttributeUsage(AttributeTargets.Method)]
public class MyCustomAttribute : Attribute
{
// . . .
}
In the example above, we’ve created a new class that inherits from System.Attribute. We’ve also applied the “AttributeUsage” attribute to our new class, specifying that it’s meant to be used just with methods.
So all of this sounds interesting, but what about the rule? Well, it states that your attribute classes should always end with the “attribute” suffix. That’s it.
The rationale behind this is our old friend, the principle of least astonishment. Adding the “attribute” suffix to an attribute class, while not required, is an established convention. Adhering to it will make your code more predictable, easy to read, understand, and maintain.
Back to You
CodeIt.Right has a very diverse set of rules. They cover a lot of ground, from design to naming, passing through coding style, exception handling, globalization and much more. In today’s post, we covered three more rules in the CodeIt.Right catalog. These rules can encourage you to write code that is more robust, predictable, and future-proof.
See you all next time for the next part in the series, with three more rules explained.
Learn more how CodeIt.Right can help you automate code reviews and improve the quality of your code.
