建立标准编码规则（四）-C#编码规范分类及实现

1 现实中的问题

在任何一个公司，每个程序员编写的习惯可能都是不一样的，大到命名空间，小到变量的名字。甚至，我们去github，里面的大牛每个开源的项目的命名规则可能都不一样。

我们通常会遇到下面的问题

1 一个webapi，版本1是一种写法，版本2认知到版本1的写法过于老旧又换了一种写法

2 一个webapi，程序员老王习惯返回大写，程序员小张喜欢返回小写

3 各个业务类似的webapi，名字都不相同，例如供应商有的用vendor 有的用supplier 有的干脆用拼音

4 公司有实际的编码规范，但检测成本太高，久而久之，公司的规范也就作废了

5 数据库规范、编码规范、api规范可能不尽相同，有冲突，制造了转换成本

这实际上会给我们增加沟通成本，当遇到bug的时候，代价是巨大的。

前段实际阿里发布了java规范，可谓行业标杆，微软为啥就没有发布一个可推广的编码规范呢。

 

2 编码规范的目的及基本情况

我认为编码规范的目的是为了使代码不依赖与代码编写者而存在。就是无限增加代码的可读性，易维护性。

我们不光要考虑程序代码的可读性还要考虑

1 数据库的可读性

2 程序代码的可读性

3 对外开放的api可读性

这三种情况的业务场景对代码规范又不尽相同。

 数据库

数据库因为受限于数据库软件，需要强制对数据库命名进行约束

SQL SERVER数据库，目前在windows上已知的是没有什么大小写限制，在Linux上未知没有试过

mysql 数据库，推荐全部小写，英文之间加下划线_，例如 useraddress 表示为user_address

oracle数据库，推荐全部大写，因为之间加下划线_，例如useraddress表示为 USER_ADDRESS

程序编码

C# 基本上 类名UpperCamelCase，公共方法 UpperCamelCase 私有方法 LowerCamelCase

对外的API

json一般建议是的 小写，下划线写法

xml到时没有什么特定的规范

 

我们这里要讨论的是，这三种如何统一，如何转换的问题

 3 如何保证编码规范的可执行性

任何脱离可执行的规范文件都是耍流氓

1.数据库，我们可以编写程序遍历数据库，检测是否合规

2.代码，可以使用Roslyn编写分析器

 

4 C#代码规范

C#代码规范可以参考StyleCop做简单的说明,一共171条规则，新版已经删除了部分规则并新增了部分规则。一个规则可能有多个代码分析器，所以实际上是看起来很多而已。

我们可以下载源码对其进行修改编辑，形成自己公司的代码规范。

SA1600	ElementsMustBeDocumented	元素必须添加注释
SA1601	PartialElementsMustBeDocumented	Partial修饰的成员必须添加注释
SA1602	EnumerationItemsMustBeDocumented	枚举必须添加注释
SA1603	DocumentationMustContainValidXml	注释必须合法(注释中的关键字不能有错误)
SA1604	ElementDocumentationMustHaveSummary	元素注释必须包含Summary关键字
SA1605	PartialElementDocumentationMustHaveSummary	Partial修饰的成员注释必须包含Summary关键字
SA1606	ElementDocumentationMustHaveSummaryText	Summary节点内部必须添加文本
SA1607	PartialElementDocumentationMustHaveSummaryText	Partial修饰的成员注释Summary节点内部必须添加文本
SA1608	ElementDocumentationMustNotHaveDefaultSummary	Summary注释不能使用编译器自带的注释文本
SA1609	PropertyDocumentationMustHaveValue	属性的注释中必须包含<Value>节点
SA1610	PropertyDocumentationMustHaveValueText	属性的注释<Value>节点必须包含文本值
SA1611	ElementParametersMustBeDocumented	参数必须注释
SA1612	ElementParameterDocumentationMustMatchElementParameters	参数的个数必须与注释里的个数一致
SA1613	ElementParameterDocumentationMustDeclareParameterName	参数的注释里必须有参数的名称
SA1614	ElementParameterDocumentationMustHaveText	参数注释节点里不能空着
SA1615	ElementReturnValueMustBeDocumented	返回值必须添加注释
SA1616	ElementReturnValueDocumentationMustHaveText	返回值注释的节点内必须有文本值
SA1617	VoidReturnValueMustNotBeDocumented	空返回值一定不能有返回值注释
SA1618	GenericTypeParametersMustBeDocumented	生成的类型(泛型)参数必须有注释
SA1619	GenericTypeParametersMustBeDocumentedPartialClass	SA1618情况如果有Partial类存在都要有注释
SA1625	ElementDocumentationMustNotBeCopiedAndPasted	各个参数的注解不能完全相同(避免copy
SA1626	SingleLineCommentsMustNotUseDocumentationStyleSlashes	单行注释不能采取三个斜线的注释方式，斜线的个数必须是二的倍数
SA1627	DocumentationTextMustNotBeEmpty	注释节点内部不能为空(必须有文本值)
SA1628	DocumentationTextMustBeginWithACapitalLetter	注释节点内部的文本必须以大写字母开头
SA1629	DocumentationTextMustEndWithAPeriod	注释节点内部的文本必须英文的句号结束
SA1630	DocumentationTextMustContainWhitespace	注释节点内部的文本必须包含空格
SA1631	DocumentationMustMeetCharacterPercentage	注释节点内部的文本中不能包含过多的字符(举例包含’---------------’是不允许的)
SA1632	DocumentationTextMustMeetMinimumCharacterLength	已经作废的规则，不允许有太短的字符串(如’Aname’中的A字母)
SA1642	ConstructorSummaryDocumentationMustBeginWithStandardText	构造函数注释标准
SA1643	DestructorSummaryDocumentationMustBeginWithStandardText	析构函数注释标准
SA1644	DocumentationHeadersMustNotContainBlankLines	注释中不能出现空白行
SA1645	IncludedDocumentationFileDoesNotExist	如果注释中包含文件，要确定这个文件存在，举例
SA1646	IncludedDocumentationXPathDoesNotExist	如果注释中包含文件，路径不存在。
SA1647	IncludeNodeDoesNotContainValidFileAndPath	如果注释中包含文件文件与路径都要合法
SA1648	InheritDocMustBeUsedWithInheritingClass	这项不明白是什么意思，还请知道的分享给我，谢谢。
SA1649	FileHeaderFileNameDocumentationMustMatchTypeName	文件头注释必须匹配类型
SA1650	ElementDocumentationMustBeSpelledCorrectly	注释不能有拼写错误(对中文支持不好，不建议使用该项)
SA1651	DoNotUsePlaceholderElements	不要使用Placeholder元素
SA1500	BracesForMultiLineStatementsMustNotShareLine  	当存在多行程序的时候，花括号不能再同一行。
SA1501	StatementMustNotBeOnASingleLine   	语句不能共享一行
SA1502	ElementMustNotBeOnASingleLine   	元素不能共享一行
SA1503	BracesMustNotBeOmitted  	花括弧即使在单行代码的情况下也不能省略。
SA1504	AllAccessorsMustBeSingleLineOrMultiLine  	读写属性，要么在同一行业要么在分多行写，不可规则不统一(个人建议分多行写)。
SA1505	OpeningBracketsMustNotBeFollowedByBlankLine 	开始的花括弧后面不能有空白行
SA1506	ElementDocumentationHeadersMustNotBeFollowedByBlankLine 	元素头部注释跟元素之间不能有空白行
SA1507	CodeMustNotContainMultipleBlankLinesInARow 	不允许有多行空白行紧挨着(个人建议写一个空白行即可)
SA1508	ClosingCurlyBracketsMustNotBePrecededByBlankLine 	结尾的花括弧不能再一个空白行之前
SA1509	OpeningBracketsMustNotBePrecededByBlankLine  	开始的花括弧不能再一个空白行之前
SA1510	ChainedStatementBlocksMustNotBePrecededByBlankLine 	相连的语句之间不能有空白行，如try语句与catch语句之间不能有空白行
SA1511	WhileDoFooterMustNotBePrecededByBlankLine  	与SA1510相同，Do语句与While语句之间不能有空白行
SA1512	SingleLineCommentsMustNotBeFollowedByBlankLine 	单行注释不能后跟空白行
SA1513	ClosingBracketMustBeFollowedByBlankLine 	结束花括弧之后必须有一个空白行
SA1514	ElementDocumentationHeaderMustBePrecededByBlankLine 	头部注解之前必须有一个空白行
SA1515	SingleLineCommentMustBePrecededByBlankLine 	单行注释之前要有一个空白行，还一种方法是不加空白行而用四个斜线注释”////”建议采取第一种方法
SA1516	ElementsMustBeSeparatedByBlankLine 	邻近的元素之间要有一个空白行
SA1517	CodeMustNotContainBlankLinesAtStartOfFile 	代码文件头部字符之前不能出现空白行
SA1518	CodeMustNotContainBlankLinesAtEndOfFile	代码文件尾部字符之后不能出现空白行
SA1119	StatementMustNotUseUnnecessaryParenthesis  	语句中不可以出现多余的括弧，无意义的括弧增加了代码的可读性
SA1400	AccessModifierMustBeDeclared  	必须定义访问修饰符
SA1401	FieldsMustBePrivate  	字段必须定义为私有的
SA1402	FileMayOnlyContainASingleClass 	一个CS文件里只定义一个类
SA1403	FileMayOnlyContainASingleNamespace  	一个CS文件只包含一个命名空间
SA1404	CodeAnalysisSuppressionMustHaveJustification   	Suppression特性(取消报告特定的静态分析工具规则冲突，允许一个代码项目上应用多个取消报告设置)必须要有合理理由
SA1405	DebugAssertMustProvideMessageText 	 参见代码：“Debug.Assert(value != true"The value must always be true.");”
SA1406	DebugFailMustProvideMessageText   	参见代码：“Debug.Fail("The code should never reach this point.");”
SA1407	ArithmeticExpressionsMustDeclarePrecedence 	算数表达式必须用明确的标明其优先级(此条与SA1119冲突)
SA1408	ConditionalExpressionsMustDeclarePrecedence 	条件表达式必须明确的标明其优先级(此条与SA1119冲突) 举例：“if (x || (y && z && a) || b)”
SA1409	RemoveUnnecessaryCode  	移除无用的代码
SA1410	RemoveDelegateParenthesisWhenPossible  	调用一个c#匿名方法不包含任何方法参数必须要包括一个空括号(本人不建议使用匿名方法
SA1411	AttributeConstructorMustNotUseUnnecessaryParenthesis 	特性构造函数如果是空参的形式，不要包括那个空括号
SA1412	StoreFilesAsUtf8	文件是否已utf8格式存储
SA1413	UseTrailingCommasInMultiLineInitializers	初始化对象变量之间使用逗号隔开
SA1300	ElementMustBeginWithUpperCaseLetter  	首字母必须大写(个人理解应该是字段以外的东西)
SA1301	ElementMustBeginWithLowerCaseLetter  	不会出现的情况
SA1302	InterfaceNamesMustBeginWithI  	接口必须以“I”字母开头
SA1303	ConstFieldNamesMustBeginWithUpperCaseLetter Const	常量首字母大写
SA1304	NonPrivateReadonlyFieldsMustBeginWithUpperCaseLetter 	非私有非制度的字段必须首字母大写
SA1305	FieldNamesMustNotUseHungarianNotation 	除了列表外的字符不可以出现匈牙利命名规则在”Style Setting”里的” Hungarian”Tab里设置
SA1306	FieldNamesMustBeginWithLowerCaseLetter 	字段名必须首字母小写
SA1307	AccessibleFieldsMustBeginWithUpperCaseLetter 	public或者internal字段首字母大写
SA1308	VariableNamesMustNotBePrefixed  	变量名不能有前缀
SA1309	FieldNamesMustNotBeginWithUnderscore  	字段名不能以下滑线开头
SA1310	FieldNamesMustNotContainUnderscore   	字段名不能包括下滑线
SA1311	StaticReadonlyFieldsMustBeginWithUpperCaseLetter 	static与readonly字段首字母大写
SA1312	VariableNamesMustBeginWithLowerCaseLetter	变量名必须是驼峰命名法
SA1313	ParameterNamesMustBeginWithLowerCaseLetter	参数名称必须是驼峰命名法
SA1314	TypeParameterNamesMustBeginWithT	类型变量必须以T开头
SX1309	FieldNamesMustBeginWithUnderscore	字段名称必须是下划线开头 这是netcore中官方建议的的编写
SX1309S	StaticFieldNamesMustBeginWithUnderscore	静态字段名称必须是下划线开头 这是netcore中官方建议的的编写
SA1200	UsingDirectivesMustBePlacedWithinNamespace   	using部分必须在Namespace内部
SA1201	ElementsMustAppearInTheCorrectOrder 	所有的元素必须出现在正确的位置上(个人不建议使用该规则，用region把一个类文件里的元素分好组即可，字段
SA1202	ElementsMustBeOrderedByAccess  	元素的修饰符有一个固定的顺序(个人不建议使用该规则，用region把一个类文件里的元素分好组即可，字段
SA1203	ConstantsMustAppearBeforeFields  	常量字段摆放在其它字段之上
SA1204	StaticElementsMustAppearBeforeInstanceElements Static  	元素摆放在前面
SA1205	PartialElementsMustDeclareAccess Partial	修饰的元素必须声明读写权限
SA1206	DeclarationKeywordsMustFollowOrder 	举例
SA1207	ProtectedMustComeBeforeInternal   	Protected在Internal之前
SA1208	SystemUsingDirectivesMustBePlacedBeforeOtherUsingDirectives  	系统级的引用在其他引用之前(格式化代码就会自动按照这个规则编排using部分)
SA1209	UsingAliasDirectivesMustBePlacedAfterOtherUsingDirectives  	using部分起别名的在最后排布
SA1210	UsingDirectivesMustBeOrderedAlphabeticallyByNamespace  	using部分按照字母顺序编排
SA1211	UsingAliasDirectivesMustBeOrderedAlphabeticallyByAliasName 	别名的按照别名的字母编排
SA1212	PropertyAccessorsMustFollowOrder  	属性按照先get在set
SA1213	EventAccessorsMustFollowOrder  	时间先remove在add
SA1214	StaticReadonlyElementsMustAppearBeforeStaticNonReadonlyElements  	StaticReadonly元素在StaticNonReadonly元素之前
SA1216	UsingStaticDirectivesMustBePlacedAtTheCorrectLocation	静态指令按顺序放
SA1217	UsingStaticDirectivesMustBeOrderedAlphabetically	静态指令按顺序放
SA1100	DoNotPrefixCallsWithBaseUnlessLocalImplementationExists	
SA1101	PrefixLocalCallsWithThis  	‘this.’前缀不能省略
SA1106	CodeMustNotContainEmptyStatements  	不允许有空白的声明
SA1107	CodeMustNotContainMultipleStatementsOnOneLine 	同一行里不允许出现多个声明语句
SA1108	BlockStatementsMustNotContainEmbeddedComments  	非法用例
SA1109	BlockStatementsMustNotContainEmbeddedRegions  	非法用例
SA1110	OpeningParenthesisMustBeOnDeclarationLine 	方法开始的括弧要在声明的那一行
SA1111	ClosingParenthesisMustBeOnLineOfLastParameter  	方法结束括弧与最后一个参数同行
SA1112	ClosingParenthesisMustBeOnLineOfOpeningParenthesis  	如果是空参的情况，开始于结束括弧在同一行
SA1113	CommaMustBeOnSameLineAsPreviousParameter 	逗号必须与前一个参数同行
SA1114	ParameterListMustFollowDeclaration 	确保参数列表与开始括号同行，或者另起一行 参数整体要在同一行
SA1115	ParameterMustFollowComma 	参数与参数之间不能隔空白行
SA1116	SplitParametersMustStartOnLineAfterDeclaration  	所有参数在同一行或者如下示例
SA1117	ParametersMustBeOnSameLineOrSeparateLines   	同上
SA1118	ParameterMustNotSpanMultipleLines 	实际调用是参数要在同一行
SA1120	CommentsMustContainText  	注释必须节点内部必须有文本
SA1121	UseBuiltInTypeAlias  	使用内嵌的类型别名
SA1122	UseStringEmptyForEmptyStrings 	示例代码：“string s = string.Empty;”不能写成” string s = ""; ”
SA1123	DoNotPlaceRegionsWithinElements  	不使用region(个人较反对这条，个人倾向于用region规整类里的元素)
SA1124	DoNotUseRegions  	不使用region(个人较反对这条，个人倾向于用region规整类里的元素)
SA1125	UseShorthandForNullableTypes  	使用简写版的可空类型 如”int?”
SA1126	PrefixCallsCorrectly  	调用类成员的时候要带上“this”前缀
SA1127	GenericTypeConstraintsMustBeOnOwnLine	泛型约束必须在同一行
SA1128	ConstructorInitializerMustBeOnOwnLine	同上
SA1129	DoNotUseDefaultValueTypeConstructor	不要使用默认值类型构造函数。
SA1130	UseLambdaSyntax	使用Lambda表达式
SA1131	UseReadableConditions	使用可读的条件
SA1132	DoNotCombineFields	
SA1133	DoNotCombineAttributes	
SA1134	AttributesMustNotShareLine	
SA1136	EnumValuesShouldBeOnSeparateLines	
SA1137	ElementsShouldHaveTheSameIndentation	
SA1139	UseLiteralSuffixNotationInsteadOfCasting	
SX1101	DoNotPrefixLocalMembersWithThis	
SA1000	KeywordsMustBeSpacedCorrectly  	关键字不能拼写错误
SA1001	CommasMustBeSpacedCorrectly 	逗号前面摆放一个空格
SA1002	SemicolonsMustBeSpacedCorrectly 	 分号前面摆放一个空格
SA1003	SymbolsMustBeSpacedCorrectly  	操作符与元素之间不加空格
SA1004	DocumentationLinesMustBeginWithSingleSpace 	“///”注释的每一行以一个空格开头
SA1005	SingleLineCommentsMustBeginWithSingleSpace  	单行注释以一个空格开头
SA1006	PreprocessorKeywordsMustNotBePrecededBySpace  	预处理关键字内部不允许出现空格 如“# if Debug”是不允许的
SA1007	OperatorKeywordMustBeFollowedBySpace   	操作必须要在一个空格之后
SA1008	OpeningParenthesisMustBeSpacedCorrectly  	开始括弧放置合理的空格
SA1009	ClosingParenthesisMustBeSpacedCorrectly  	结尾括弧放置合理的空格
SA1010	OpeningSquareBracketsMustBeSpacedCorrectly 	开始方括号放置合理的空格
SA1011	ClosingSquareBracketsMustBeSpacedCorrectly   	结束方括号放置合理的空格
SA1012	OpeningCurlyBracketsMustBeSpacedCorrectly  	开始花括号放置合理的空格
SA1013	ClosingCurlyBracketsMustBeSpacedCorrectly 	结束花括号放置合理的空格
SA1014	OpeningGenericBracketsMustBeSpacedCorrectly 	同上
SA1015	ClosingGenericBracketsMustBeSpacedCorrectly 	同上
SA1016	OpeningAttributeBracketsMustBeSpacedCorrectly  	特性开始括号同上
SA1017	ClosingAttributeBracketsMustBeSpacedCorrectly 	特性结尾括号同上
SA1018	NullableTypeSymbolsMustNotBePrecededBySpace 	空类型前不放置空格
SA1019	MemberAccessSymbolsMustBeSpacedCorrectly  	成员访问关键字前后有空格
SA1020	IncrementDecrementSymbolsMustBeSpacedCorrectly	自增自减关键字要有空格
SA1021	NegativeSignsMustBeSpacedCorrectly  	负号要有空格
SA1022	PositiveSignsMustBeSpacedCorrectly   	正号要有空格
SA1023	DereferenceAndAccessOfMustBeSpacedCorrectly	
SA1024	ColonsMustBeSpacedCorrectly  	冒号运算符要有空格
SA1025	CodeMustNotContainMultipleWhitespaceInARow  	同一行不允许出现多个空格
SA1026	CodeMustNotContainSpaceAfterNewKeywordInImplicitlyTypedArrayAllocation  	new关键字之后不允许出现空格
SA1027	TabsMustNotBeUsed  	不用tab字符
SA1028	CodeMustNotContainTrailingWhitespace	代码后面不能有空格
SA0001	XmlCommentAnalysisDisabled	禁用XML注释
SA0002	InvalidSettingsFile	无效的配置文件