Professional C# 6 and .NET Core 1.0. Christian Nagel

don’t match up to the line numbers in the files or the filenames you are editing. The #line directive can be used to restore the match. You can also use the syntax #line default to restore the line to the default line numbering:

      #pragma

      The #pragma directive can either suppress or restore specific compiler warnings. Unlike command-line options, the #pragma directive can be implemented on the class or method level, enabling fine-grained control over what warnings are suppressed and when. The following example disables the “field not used” warning and then restores it after the MyClass class compiles:

C# Programming Guidelines

      This final section of the chapter supplies the guidelines you need to bear in mind when writing C# programs. These are guidelines that most C# developers use. When you use these guidelines, other developers will feel comfortable working with your code.

      Rules for Identifiers

      This section examines the rules governing what names you can use for variables, classes, methods, and so on. Note that the rules presented in this section are not merely guidelines: they are enforced by the C# compiler.

      Identifiers are the names you give to variables, to user-defined types such as classes and structs, and to members of these types. Identifiers are case sensitive, so, for example, variables named interestRate and InterestRate would be recognized as different variables. Following are a few rules determining what identifiers you can use in C#:

      • They must begin with a letter or underscore, although they can contain numeric characters.

      • You can’t use C# keywords as identifiers.

      The following table lists the C# reserved keywords.

      If you need to use one of these words as an identifier (for example, if you are accessing a class written in a different language), you can prefix the identifier with the @ symbol to indicate to the compiler that what follows should be treated as an identifier, not as a C# keyword (so abstract is not a valid identifier, but @abstract is).

      Finally, identifiers can also contain Unicode characters, specified using the syntax \uXXXX, where XXXX is the four-digit hex code for the Unicode character. The following are some examples of valid identifiers:

      • Name

      • Überfluß

      • _Identifier

      • \u005fIdentifier

      The last two items in this list are identical and interchangeable (because 005f is the Unicode code for the underscore character), so obviously these identifiers couldn’t both be declared in the same scope. Note that although syntactically you are allowed to use the underscore character in identifiers, this isn’t recommended in most situations. That’s because it doesn’t follow the guidelines for naming variables that Microsoft has written to ensure that developers use the same conventions, making it easier to read one another’s code.

      NOTE You might wonder why some newer keywords added with the recent versions of C# are not in the list of reserved keywords. The reason is that if they had been added to the list of reserved keywords, it would have broken existing code that already made use of the new C# keywords. The solution was to enhance the syntax by defining these keywords as contextual keywords; they can be used only in some specific code places. For example, the async keyword can be used only with a method declaration, and it is okay to use it as a variable name. The compiler doesn’t have a conflict with that.

      Usage Conventions

      In any development language, certain traditional programming styles usually arise. The styles are not part of the language itself but rather are conventions – for example, how variables are named or how certain classes, methods, or functions are used. If most developers using that language follow the same conventions, it makes it easier for different developers to understand each other’s code – which in turn generally helps program maintainability. Conventions do, however, depend on the language and the environment. For example, C++ developers programming on the Windows platform have traditionally used the prefixes psz or lpsz to indicate strings – char *pszResult; char *lpszMessage; – but on Unix machines it’s more common not to use any such prefixes: char *Result; char *Message;.

      Notice from the sample code in this book that the convention in C# is to name variables without prefixes: string Result; string Message;.

      NOTE The convention by which variable names are prefixed with letters that represent the data type is known as Hungarian notation. It means that other developers reading the code can immediately tell from the variable name what data type the variable represents. Hungarian notation is widely regarded as redundant in these days of smart editors and IntelliSense.

      Whereas many languages’ usage conventions simply evolved as the language was used, for C# and the whole of the .NET Framework, Microsoft has written very comprehensive usage guidelines, which are detailed in the .NET/C# MSDN documentation. This means that, right from the start,NET programs have a high degree of interoperability in terms of developers being able to understand code. The guidelines have also been developed with the benefit of some 20 years’ hindsight in object-oriented programming. Judging by the relevant newsgroups, the guidelines have been carefully thought out and are well received in the developer community. Hence, the guidelines are well worth following.

      Note, however, that the guidelines are not the same as language specifications. You should try to follow the guidelines when you can. Nevertheless, you won’t run into problems if you have a good reason for not doing so – for example, you won’t get a compilation error because you don’t follow these guidelines. The general rule is that if you don’t follow the usage guidelines, you must have a convincing reason. When you depart from the guidelines you should be making a conscious decision rather than simply not bothering. Also, if you compare the guidelines with the samples in the remainder of this book, you’ll notice that in numerous examples I have chosen not to follow the conventions. That’s usually because the conventions are designed for much larger programs than the samples; although the guidelines are great if you are writing a complete software package, they are not really suitable for small 20-line standalone programs. In many cases, following the conventions would have made the samples harder, rather than easier, to follow.

      The full guidelines for good programming style are quite extensive. This section is confined to describing some of the more important guidelines, as well as those most likely to surprise you. To be absolutely certain that your code follows the usage guidelines completely, you need to refer to the MSDN documentation.

      Naming Conventions

      One important aspect of making your programs understandable is how you choose to name your items – and that includes naming variables, methods, classes, enumerations, and namespaces.

      It is intuitively obvious that your names should reflect the purpose of the item and should not clash with other names. The general philosophy in the .NET Framework is also that the name of a variable should reflect the purpose of that variable instance and not the data type. For example, height is a good name for a variable, whereas integerValue isn’t. However, you are likely to find that principle is an ideal that is hard to achieve. Particularly when you are dealing with controls, in most cases you’ll probably be happier sticking with variable names such as confirmationDialog and chooseEmployeeListBox, which do indicate the data type in the name.

      The following sections look at some of the things you need to think about when choosing names.

      Casing of Names

      In many cases you should use Pascal casing for names. With Pascal casing, the first letter of each word in a name is capitalized: EmployeeSalary, ConfirmationDialog, PlainTextEncoding. Notice that nearly all the names of namespaces, classes, and members in the base classes follow Pascal casing. In particular, the convention of joining words using the underscore character