Code is the product of software development process, the function of code is compiled by the compiler after running, to achieve the desired effect (function, stability, security, etc.), and another important role is for people to read. For machines, as long as the code is correct, the program can be correctly run, but human beings are different. If the code is written in disorder, it will cause obstacles to the code reading, resulting in the code cannot be maintained, and even lead to high cost activities such as code reconstruction, so it is imperative to standardize the code.

This article introduces the code specification and related tools from the following aspects.

  • Introduction to.net code specifications

  • Code format specification

    • Naming conventions
    • The layout specification
    • Annotation specifications

  • Code usage specification

  • Common code specification tools

  • summary

Introduction to.net code specifications

Article began mentioned code is to see people, the purpose of the code rules is to create a unified specification to maintain the cleanliness of the code, so that to improve the maintainability of the code, but beyond that can also be some of the code of best practices that are as part of the specification, it also can improve the performance and security of the code. Generally speaking.Net code specification mainly includes code format specification and code usage specification. The former ensures code readability and the latter ensures code execution efficiency and security.

Code format specification

The main purpose of code format specification is to unify the code format and avoid the unique code writing way of developers, so that all developers of the project can quickly read the code developed by other people. The code format specification mainly includes the following aspects:

Note: in addition to the following specification, for a project and engineering structure should be the directory structure (can also be interpreted as code specification), the specification of engineering structures can be different with different project, but the unified specification can improve the efficiency of search efficiency and coding (new team members won’t doubt code should be put where).

Naming conventions

Naming conventions mainly involve namespaces, types, interfaces, attributes, methods, and variables. The main naming conventions include:

  • Namespaces, types, enumerated types, enumerated values, events, properties, methods, and constants are named using Pascal(uppercase) naming.

Example: public class PersonManager {}

  • Use Camel() to name parameters, variables, and fields.

Example: private string userName; Do not use abbreviations, except those that can be agreed upon, such as URL and IO. Example: System. IO;

  • The interface is named with the prefix I.

Public interface IConvertor {}

  • Abstract classes are named with either an Abstract prefix or a Base suffix.

Public abstract class PersonBase {}

  • Exception types are suffixed with Exception.

Example: public class CustomException {}

  • Use meaningful names for everything, and make sure the spelling and grammar are correct. Avoid pinyin (with the exception of general pinyin such as place names).

Public string Name {get; set; } public string N {get; set; }

The layout specification

The purpose of layout specifications is to make code cleaner and more readable. The main specifications are:

  • The code is indented to 4 Spaces.

The left and right curly braces must be a single line, except when the parentheses are empty. For example, public void WriteLog(string log) {console. WriteLine(log); }

public void EmptyMethod(string log) {}

  • Use of parentheses:

    • If /for/while/do

if (x == 1)

    • Operators need Spaces around them:

a = c + b;

  • A single line of code is limited to 120 characters.

    • The second line is indented 4 Spaces from the first line, starting on the third line without indentation.
    • Operator and method call “. A newline is required, but a comma is not.

Example: to WebHost. CreateDefaultBuilder (args). UseStartup < Startup > (). The Build (); App.Method(a + b, c);

Annotation specifications

Comments are used to write code to explain, including function description and implementation description, which can greatly improve the readability of the program, in addition to the specification of comments can also be used to generate the corresponding API documentation tool, C# annotation specification has the following several:

  • Class notes

Example: ///

// This is an Entity Class for Post. ///

Public Class Post

  • Properties and method comments:

///

/// Get post with id ///

/// post’s identity ///

post instance
 public Post GetPostById(int id)

  • Single-line comments:

//this is a single line comment

  • Multi-line comments:

/* this is comment1 this is comment2 */

Code usage specification

The use of the code, or code of best practice “(of course good format specification is also a kind of best practice), they are according to the principle of the realization of the code/run and carries on the practice of the specific application scenarios best practices, the use of these solutions in addition to improve code to read lines, can also reduce the program bugs and improve application performance and security, Such as the following aspects:

  • Use language features

This: Use this to distinguish attributes from variables and static members of a type to improve program readability. Var: Appropriate use of var can improve the development efficiency without affecting the readability of the program, such as when the specific type of the return value is not known or does not need to be known. Example:

　　

From this example: weblogs.asp.net/dixin/cshar…

  • String interpolation: string interpolation is a C#6.0 feature to improve readability of programs:

Ex. :

　　

  • abnormal

    • When an application does not conform to expectations, it should throw an exception and let the application handle it upstream.
    • Use built-in exception types in C# whenever possible.
    • Catching exceptions must be handled.
    • Get the specified Exception instead of using Exception.

  • Security code

Reference: docs.microsoft.com/zh-cn/dotne… More specifications can be found at docs.microsoft.com/en-us/dotne… Code usage specifications are a broad topic. In addition to the above general specifications, you can also set rules for OOP and development frameworks based on the actual situation. Developing with a common specification makes your code much easier to manage.

Common code specification tools

  • Visual Studio

VS is a very powerful IDE and certainly does not lack support for code specifications among its many features.

  • StyleCop

StyleCop is a code analysis tool, and there are two versions of StyleCop and StyleCop Analyzers. StyleCop is applicable to all VERSIONS of VS2010 to VS2017. StyleCop is designed to analyze code at compile time. StyleCop Analyzers only support VS2015+, which is based on. Net’s Roslyn compilation framework, which supports real-time analysis of code at development time (no longer need to wait for compilation). StyleCop:github.com/StyleCop/St… StyleCop Analyzers:github.com/DotNetAnaly…

  • Resharper

Resharper is a vS-paid plug-in developed by JetBrains, which not only includes code analysis, but also code generation, compilation, testing, debugging, and more. VS2017 compared with Resharper features www.jetbrains.com/resharper/d…

  • EditConfig

EditConfig is a cross-editor /IDE code-style consistency tool (protocol/plug-in) that is now supported in VS2017

  • DocFx

DocFx is an API document generation tools that use DocFx can quickly set up a program to use, and the API documentation, style can be reference: DocFx tutorial: dotnet. Making. IO/DocFx/tutor… The API documentation: dotnet. Making. IO/docfx/API/M…

summary

In c # programming specification is mainly introduced in this paper, and the specification is divided into two types, respectively is the format specification and the use of standard, the main purpose is to make the code format to achieve consistency, the latter is the use of the provisions of the code, maximize reduce different experience developers to write code quality, improve the readability of the program, performance, stability and security. Programming specification is a very important work in the development process, it is related to whether the code can be maintained, improving maintainability can reduce the high cost of adding and removing team members, adding features, code changes, etc. The formulation of programming specifications is not simple, different people have different understanding of programming specifications, especially code usage specifications, it requires the makers must have rich experience in code development and code optimization. In order to ensure that the specification of the formulation, personally think that need to be set before modification manner, set in order not to delay the development work, before the start of the development work set specification can be developed according to the specification, after modification, the first is found in the development process is not reasonable place to modify (mouth says, practice the truth), the other is with the improvement of ability of team, More code usage best practices can be summarized. Some common specification tools are introduced at the end of the article, which will be covered in detail in the next article. Net platform under the specification tool for its use.

Attached is the Java specification defined by Alibaba: github.com/alibaba/p3c…

Reference: docs.microsoft.com/en-us/dotne… Docs.microsoft.com/en-us/dotne… Docs.microsoft.com/zh-cn/dotne… Orcharddojo.net/orchard-res… www.codeproject.com/articles/11… Weblogs.asp.net/dixin/cshar… Github.com/dotnet/docf… Github.com/alibaba/p3c…

This paper links: www.cnblogs.com/selimsong/p…

Good code is tube out — talk about it. Net Core code management approach and implementation