We learned in Chapter 4 that our application code can involve input and output and that the input and output can be completed in the console window. The output from our application is the visible part for an end user and it is important they have a good experience when seeing the output. The user experience is often referred to as the UX and can involve the developer making use of colors, emphasis, layout, etc. to make the application readable and pleasing to look at.
This chapter will concentrate on how to create a good user experience for the developer rather than the end user, when they are creating, reading, and maintaining code. It is particularly important to understand that as developers we should be having a good user experience when we look at any application code, whether it is our code or someone else's.
Adding astutely placed comments as explanations in our code.
Not overusing comments. Not everything will need a comment if the code is written well, but comments can be a big help to the reader.
Our variable names being such that they explain the variable purpose.
Our method names being such that they explain the method purpose.
Our class names being such that they explain the purpose of the class.
This code coloring within Visual Studio is one way in which Microsoft has attempted to help developers who write and read code.
Note
In the code examples we will use throughout the chapters in this book, there will be lots of comments used to help us understand the code, but if these were commercial applications, we would not have as many comments.
Make sure to read the code comments in the course code examples as they have invaluable information that adds to and supplements the text of this book. They are in the code to help clarify what we are doing and why we are doing certain things. So we should not ignore them. We should read them, but we do not necessarily have to type the comments into our code.
A description indicating the purpose of the application
Information about the developer or developers
The date on which the program was first created
The date when maintenance occurred, for example, when lines of code were amended, added, or deleted
What a line of code or lines of code are doing
The purpose of a method
The purpose of a delegate that is linked to a method
The purpose or intrinsic workings of a complicated formula
C# Single-Line Comments
Single-line comments in C#, and many other programming languages, are preceded by two forward slash symbols , //. The // indicates a single-line comment, which is generally used for brief comments. Some developers will write the comments above the code, while others will use the comment on the same line as the code. Both types are shown in Listings 5-1, 5-2, and 5-3.
Example 1
Single-line comments
Example 2
Single-line comment above code
Example 3
Inline comment
Projects and Solutions
Before we start writing the code for this chapter, let us think about the project we created in Chapter 4. When we created it, we gave the project the name ConsoleV1, which was perfectly fine at the time, but definitely not very descriptive. We will talk more about naming later. Now, when we wish to code the example for this chapter, where will we put our code?
The existing project in the solution, where we can amend the existing class or create a new class to hold the new code
A new folder within the existing project
A new project that we can create
ConsoleApplications
Coursecode
Chapter4
If we decide that a name change would be appropriate, we can rename the project, but will the code in the class need to be changed? No, this will not affect the code in the project.
- 1.
Make sure the solution and project are open in Visual Studio.
- 2.
Right-click the ConsoleV1 project name.
- 3.
Choose Rename , as shown in Figure 5-2.
- 4.
Name the project Chapter4.
- 5.
Press the Enter key.
- 6.
Right-click the CoreCSharp solution name in the Solution Explorer panel.
- 7.
Choose Add, as shown in Figure 5-4.
- 8.
Choose New Project.
- 9.
Choose Console App from the listed templates that appear, as shown in Figure 5-5.
- 10.
Click the Next button.
- 11.
Name the project Chapter5, leaving it in the same location, as shown in Figure 5-6.
- 12.
Click the Next button.
- 13.
Choose the framework to be used, which in our projects will be .NET 6.0 or higher, as shown in Figure 5-7.
- 14.
Click the Create button.
New .NET 6 Templates
A “traditional” code example
Code template in .NET 6
This new template code reflects new C# 10 features, which allow us to simplify our code. The two template codes, Listings 5-4 and 5-5, are effectively the same thing and will work in C# 10. C# 10 therefore allows us to
Write the code for the Main( ) method, leaving out the namespace, class, Main( ) method, and using statements.
This is very nice, when you know what you are doing and have a good understanding of the core C# programming fundamentals. For now, and throughout the chapters in this book, we will overwrite the code in the new template and work with the “older” format, where we will code the namespace name and the class name, include the Main() method when required, and display all the using statements. If we switch off the top-level statements by ticking the checkbox once on any project creation, the option will be remembered for future projects. All of this will become abundantly clear when we code the examples. By using our format in the chapter examples, it will allow us to understand C# code much better and be able to read code already written in this format, and we can then start using the “shortcut” style for future applications.
- 1.
Double-click the Program.cs file in the Chapter5 folder.
- 2.
Delete the two lines of code in the Program.cs file.
- 3.
Double-click the Program.cs file in the Chapter4 project.
- 4.
Highlight all of the code.
- 5.
Choose Copy from the Edit menu.
- 6.
Double-click the Program.cs file in the Chapter 5 folder.
- 7.
Paste the code copied from the Chapter 4 file.
- 8.
Amend the code to change the namespace to Chapter5, as in Listing 5-6.
Namespace changed
- 9.
Add comments to the program code, as in Listing 5-7.
Single-line comments
- 10.
Right-click the Chapter5 project in the Solution Explorer panel.
- 11.
Choose Set as Startup Project.
- 12.
Click the File menu.
- 13.
Choose Save All.
- 14.
Click the Debug menu.
- 15.
Choose Start Without Debugging.
- 16.
Press any letter on the keyboard to continue, for example, a.
- 17.
Press the Enter key.
- 18.
Press the Enter key.
- 19.
Press the Enter key.
The code has produced an application that performs exactly as it did before we added the comment lines. So comments are for a reader of the code and do not change what the application does. The comments are ignored in the process of building and compiling the program from the source code we have written.
C# Multiple-Line Comments
Multiple-line comment
- 1.
Add the multiple-line comments, as in Listing 5-9, to our program code .
Multiple-line comments
- 2.
Click the File menu.
- 3.
Choose Save All.
- 4.
Click the Debug menu.
- 5.
Choose Start Debugging.
- 6.
Press any letter on the keyboard to continue, for example, a.
- 7.
Press the Enter key.
- 8.
Press the Enter key.
- 9.
Press the Enter key.
Chapter Summary
In this chapter we have added comments to our code to help us understand what the code is doing and to reinforce certain aspects of the C# programming language. We have used comments to give information about namespaces and the Main() method. Remember the golden rule: only use comments when they are required and the code itself is not self-documenting.
The namespace
The project
The class
The variables
The constants
If we cannot write legible code, then it is unlikely we will be able to write legible comments.
Harsh? Maybe, but it reinforces the point that comments should not be a replacement for self-documenting code.
In finishing this chapter and increasing our knowledge, we are advancing to our target and making good progress.