代码是软件开发过程的产物,代码的做用是经过编译器编译后运行,达到预期的效果(功能、稳定性、安全性等等),而另一个重要做用是给人阅读。对于机器来讲只要代码正确就可以正确的运行程序,可是人不一样,若是代码编写混乱就会对代码阅读形成障碍,致使代码没法维护,甚至会致使代码重构等高成本活动,因此规范代码势在必行。html
本文从如下几个方面介绍代码规范以及相关工具。git
文章开始提到过代码是给人看的,代码规范的目的在于建立一个统一的规范来保持代码的整洁,这样有利于提升代码的可维护性,但除此以外还能够将一些代码的最佳实践也做为规范的一部分,这样还能够提升代码的性能和安全性。
通常来讲.Net的代码规范主要有:代码格式规范、代码使用规范,前者保证代码可读性后者保证代码执行效率和安全性。github
代码格式规范主要的目的是统一代码编写格式,避免开发人员独特的代码编写方式,以便于项目的全部开发人员能快速的阅读其余人员开发的代码,代码格式规范主要有如下几个方面:web
注:除如下规范外,对于一个工程来讲应该还有工程结构规范(也能够理解为代码目录结构规范),工程结构规范可能因项目不一样而不一样,可是统一规范能够提升代码查找效率和开发效率(团队新成员不会再疑惑代码应该放哪里)。编程
命名规范主要涉及命名空间、类型、接口、属性、方法、变量等相关命名,其主要规范有:api
例:public class PersonManager {}安全
例:private string userName;
禁止使用缩写,除URL、IO等能达成共识的缩写除外,使用缩写可全大写。
例:System.IO;app
例:public interface IConvertor {}框架
例:public abstract class PersonBase {}asp.net
例:public class CustomException {}
例: public string Name {get; set;}
反例: public string N {get; set;}
布局规范的目的是使代码变得整洁,提升代码可读性,其主要规范有:
左右花括号必须独自一行,括号内容为空时除外:
例:public void WriteLog(string log)
{
Console.WriteLine(log);
}
public void EmptyMethod(string log) {}
if (x == 1)
a = c + b;
例:WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.Build();
App.Method(a
+ b,
c);
注释用来对编写的代码进行说明,包括功能说明以及实现说明,这样能够大大的提升程序的可读性,另外规范的注释还能够经过工具来生成相应的API文档,C#的注释规范有如下几种:
例:/// <summary>
/// This is a Entity Class for Post.
/// </summary>
public class Post
/// <summary>
/// Get post with id
/// </summary>
/// <param name="id">post's identity</param>
/// <returns>post instance</returns>
public Post GetPostById(int id)
//this is a single line comment
/*
this is comment1
this is comment2
*/
代码的使用规范,或者说是代码编写的最佳“实践”(固然优良的格式规范也是一种最佳实践),它们是根据代码的实现/运行原理以及特定的应用场景进行实践的最佳方案,这些方案的使用除了能够提升代码的可读行外,还能够减小程序Bug、提升程序性能及安全性,如如下几个方面:
this:使用this区分类型中的属性与变量、静态成员,能够提升程序可读性。
var:适当的使用var能够提升开发效率且不影响程序可读性,如在不知道返回值具体类型或者不须要知道类型的时候。
反例:
本例来自:https://weblogs.asp.net/dixin/csharp-coding-guidelines-4-types
例:
参考:https://docs.microsoft.com/zh-cn/dotnet/standard/security/secure-coding-guidelines
更多规范可参考:https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions
代码使用规范是一个普遍的话题,除了以上一些通用的规范以外,还能够对OOP以及开发框架等方面根据实际状况制定规则,使用统一的规范进行开发可让代码变得更加容易管理。
VS是很是强大的IDE,在众多功能中固然不会缺乏对代码规范的支持。
StyleCop是一个代码分析工具,StyleCop有两个版本StyleCop和StyleCop Analyzers,前者适用于VS2010-VS2017全部版本,它的原理是在编译时对代码进行分析,而StyleCop Analyzers仅支持VS2015+,它基于.Net的roslyn编译框架实现的,它支持开发时对代码进行实时分析(再也不须要等编译)。
StyleCop:https://github.com/StyleCop/StyleCop
StyleCop Analyzers:https://github.com/DotNetAnalyzers/StyleCopAnalyzers
Resharper是jetbrains公司开发的一个VS收费插件,它不只包含了代码分析,还具有了代码生成、编译、测试、调试等功能。
VS2017与Resharper的功能比较https://www.jetbrains.com/resharper/documentation/comparisonMatrix_R2018_1_vs2017.html
EditConfig是一个跨编辑器/IDE的代码风格一致性维护工具(协议/插件),如今VS2017已经支持EditConfig
DocFx是一个API文档生成工具,使用DocFx能够快速的搭建一个程序使用、及API文档,样式可参考:
DocFx教程:http://dotnet.github.io/docfx/tutorial/docfx_getting_started.html
API文档:http://dotnet.github.io/docfx/api/Microsoft.DocAsCode.html
本文主要介绍了C#中的编程规范,并将规范分为了两个类型,分别是格式规范和使用规范,前者主要目的是让代码格式达到一致性,后者则是规定了代码的使用方法,最大化的减小不一样经验开发人员编写代码的质量,提升程序的可读性、性能、稳定性及安全性。
在开发过程当中编程规范是一项很是重要的工做,它关系着代码是否可以被维护,提升可维护性能够减小团队成员增减、功能新增、代码变动等带来的高成本。
编程规范的制定并不简单,不一样的人对编程规范也有不一样的理解,特别是代码的使用规范,它要求制定者必需要有丰富的代码开发以及代码优化经验。为了确保规范可以顺利的制定,我的认为须要以先制定后修改的方式进行,先制定是为了避免耽误开发工做,在开发工做开始以前制定好规范便可按规范开发,后修改,其一是在开发过程当中发现不合理的地方进行修改(口说无凭,实践出真理),另外是随着团队能力的提升,能够总结更多的代码使用最佳实践。
文章的最后介绍了一些经常使用的规范工具,下篇文章将详细的介绍.Net平台下的规范工具以其使用。
参考:
https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/
https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions
https://docs.microsoft.com/zh-cn/dotnet/standard/security/secure-coding-guidelines#application-code-that-is-not-a-reusable-component
https://orcharddojo.net/orchard-resources/Library/DevelopmentGuidelines/BestPractices/CSharp
https://www.codeproject.com/articles/118853/some-best-practices-for-c-application-development
https://weblogs.asp.net/dixin/csharp-coding-guidelines-1-fundamentals
https://github.com/dotnet/docfx
https://github.com/alibaba/p3c/blob/master/%E9%98%BF%E9%87%8C%E5%B7%B4%E5%B7%B4Java%E5%BC%80%E5%8F%91%E6%89%8B%E5%86%8C%EF%BC%88%E8%AF%A6%E5%B0%BD%E7%89%88%EF%BC%89.pdf