Introduction
Coding conventions are a set of guidelines for writing code that is consistent, readable, and comprehensible. They are also sometimes called programming conventions, style guides or coding standard. These conventions cover various aspects of the code, such as naming conventions, indentation, commenting, and formatting. By following these conventions, developers can quickly understand the structure and purpose of the code, which makes it easier to debug and maintain the code. Additionally, conventions ensure that the code is consistent across a team or organization, which can improve collaboration and communication among developers.
The term “clean code” refers to a programming style that also prioritizes maintainability and scalability by following principles like clarity, simplicity, consistency, and modularity. Clean code is important for the main developers and other developers who will read and maintain it in the future. Writing it requires discipline and attention to detail, but the benefits are well worth the effort. It can improve the speed and efficiency of development, reduce bugs and errors, and make the codebase more scalable and maintainable.
Writing clean code and following conventions is important for every programmer, but especially for C# developers since the C# language has a strict syntax and object-oriented features that can make it challenging to write readable and efficient code. C# is a modern, object-oriented programming language developed by Microsoft and was first released in 2002. It is based on the C programming language and is primarily designed for building Windows desktop applications and games, web applications, and mobile apps. This article will go through the most useful tips for writing clean code in C#, along with some coding examples so you can better grasp the idea of what’s being explained.
Best Practices for Writing Clean Code
Since the importance of writing clean code and following coding conventions has already been explained, let us now take a look at some tips on how to actually write such code, with a detailed explanation and a coding example for each one of those tips.
Follow Formatting Rules
Keeping the code well-structured and organized is essential for having a successful project and avoiding any future headaches. Therefore, every development team is supposed to come up with a specific style guide that specifies the formatting requirements for the code that they’re writing. So, the best way to format the code and achieve better readability is by following this style guide that your team has defined, as well as following some commonly accepted layout conventions. Using a good code editor or the C# IDE will make the writing process easier, as it handles the formatting for you.
Let us now look at examples of how formatted vs unformatted code looks like:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
# Bad practice class Car { static void Main(string[] args) { powerLevel = 90; Console.WriteLine("Car class."); // print "Car class" } } # Good practice class Car { static void Main(string[] args) { // Output the name of the class. Console.WriteLine("Car class."); } } |
Give Meaningful Names
When naming variables or methods, always make sure to give a meaningful name that makes sense and is easy to remember. Although this doesn’t seem like a big deal now, there will be a lot of unnecessary confusion and complications once the project grows and becomes more complex. A good name is concise and helps the developers understand the usage and context of that specific method or variable. Thinking of variable names might be a time-consuming process, but it’s an absolutely necessary one since it will save you a lot of time in the future.
Here’s an example:
|
1 2 3 4 5 |
# Bad practice string yyyymmdd; # Good practice string currentDateString; |
Use Camel Case Notation
Camel case notation is when the initial letter of the variable’s first word is in lowercase, and the first letter of each subsequent word is in upper case. Camel casing should be used when naming local variables, method arguments, parameters, and fields. Also, keep in mind that, when naming internal or private fields, they should be prefixed with _.
Below are two examples of when the camel case should be employed:
|
1 2 3 4 5 6 7 |
# Bad practice int Sum; private DateTime Date; # Good practice int sum; private DateTime _date; |
Use Pascal Case Notation
Pascal case notation is when all the first letters of each word are in upper case. Pascal casing should be used when naming classes, records, structs, and public members of types (methods, fields, properties). Also, this type of casing should be used when naming interfaces, and the name should be prefixed with an I.
Below are two examples of when the pascal case should be employed:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
# Bad practice public class program public interface queue public void print() { Console.WriteLine("This is a print method!"); } # Good practice public class Program public interface IQueue public void Print() { Console.WriteLine("This is a print method!"); } |
Use the && and || operators
Use && and || instead of & and | when making comparisons to prevent exceptions and improve performance by bypassing pointless comparisons. When the && operator is used, the first condition is first checked. If it is found to be false, the second condition is not even checked because the && operator (AND) only returns true if both conditions are true. Therefore, the result will always be false, no matter the output of the second condition. However, when the operator & is used, both criteria are always checked, which can decrease the application’s performance. The same applies to the || (OR) operator.
Let us better understand this by looking at a scenario where the & operator would throw an exception, but the && would not, thus recognizing the importance of the latter:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
# Bad practice # This will throw an exception int x = 0; int y = 15; if ((x != 0) & (y / x < 0)) { # Do something } # Good practice int x = 0; int y = 15; if ((x != 0) && (y / x < 0)) { # Do something } |
Follow Commenting Conventions
Putting comments on the code you wrote is sometimes essential for making it understandable and readable. However, keep in mind that adding too many comments may make it messy, so try to write self-explanatory code whenever possible and avoid throwing random comments into the program here and there. When you do need to put a comment, make sure to follow the conventions stated below, so that you avoid writing bad and unnecessary comments.
Here are some guidelines on commets:
– Comments should start with an uppercase letter.
– Comments should end with a period.
– Comments should be on a separate line.
– Comments should not be enclosed in blocks of formatted asterisks.
– There should be one space between the comment delimiter (//) and the comment text, as seen in the example below.
In order to better understand when a comment might be unnecessary, and when it is absolutely helpful, take a look at these examples:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
# Bad practice class Car { static void Main(string[] args) { powerLevel = 90; Console.WriteLine("Car class."); // print "Car class" } } # Good practice class Car { static void Main(string[] args) { // Output the name of the class. Console.WriteLine("Car class."); } } |
Write Reusable Code
Writing reusable code is important since having fewer lines of code will make the project more efficient. What is meant by reusable code? Well, it means that there shouldn’t be multiple copies of the same function in different classes, or there shouldn’t be the same chunks of code in different parts of the code. Rather than that, that repeating code should be encapsulated in a function, and if that function is used in multiple classes, it should be created once and then referenced wherever needed. That way, the function will be reusable, and what’s more, if changes are necessary, they will be applied in one place only, instead of going through all classes that have that function.
Avoid Magic Numbers and Magic Strings
First of all, what are magic numbers and magic strings? They are strings/numbers that are specified in the code and directly affect the way the program behaves. To avoid such variables means avoiding hardcoded strings or numbers within the application, and there are multiple reasons why that is a good idea. Firstly, keeping track of such variables can become very difficult as the application gets more complex. Secondly, these strings may be connected to many types of external references, such as file names or file paths, which may cause an issue once the file name or location changes. Moreover, magic variables oftentimes duplicate themselves, making them prone to errors due to their inability to be automatically updated.
The code snippet below is an example of how to avoid magic numbers by declaring a constant:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# Bad practice if (age < 18) { # Do something; } # Good practice public const int legalAge = 18; if (age < legalAge) { # Do something; } |
Don’t Forget the Power of the Ternary Operator
The ternary conditional operator, also known as the conditional operator ?:, evaluates a Boolean expression to determine if it evaluates to true or false and then returns the outcome of one of the two expressions. That way, instead of writing multiple lines of code, we can write only one line that does the exact same thing! However, keep in mind that the ternary operator should be applied for simple if-statements only because it can get very messy quickly in case the condition and logic are rather complex.
Here’s a practical example of how it works:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
# Bad practice public string CheckAge(int age) { if (age < 18) { return "The person has less than 18 years."; } else { return "The person has 18 years or more."; } } # Good practice public string CheckAge(int age) { return age < 18 ? "The person has less than 18 years." : "The person has 18 years or more."; } |
Go For String Interpolation
An interpolated string is specified by the ‘$’ special character that is being put right in front of the string literal itself, as well as the interpolation expressions that it most often contains. The interpolated string feature was first introduced in C# 6 and has been widely utilized ever since due to its readable and convenient syntax. When the result string is being created from the interpolation string, the string representations of the expression results are used to replace items with interpolation expressions.
Let’s grasp the concept of string interpolation by looking at the following code example:
|
1 2 3 4 5 6 7 8 9 10 11 |
# Bad practice string name = "Anna"; int age = 15; Console.WriteLine("This is " + name + " and she is " + age + " years old"); # Good practice string name = "Anna"; int age = 15; Console.WriteLine($"This is {name} and she is {age} years old"); |
Summary
Writing highly maintainable, well-structured, and optimized code that can also be easily maintained by other developers who will inherit it is one of a C# programmer’s most crucial, yet challenging skills. It’s important to remember that writing clean code is a moving target that isn’t always simple to accomplish. Writing clean code requires patience, practice, and feedback, and it might change over time as a project develops, new technologies are released, and new team members join the effort.
The article goes through some of the most important tips for writing clean and maintainable code in C#. It suggests using meaningful and descriptive variable names, using camel case and pascal case notations, using the ternary and binary conditional logical operators, and following formatting and commenting conventions and best practices. Additionally, the article emphasizes the importance of writing reusable code, as well as utilizing string interpolation and avoiding magic numbers and strings. All in all, the article stresses the importance of writing code that is easy to understand and alter, in order to reduce the likelihood of bugs and errors and improve the overall development process.
