VS 编码规范---- 代码注释设置

一个良好的代码风格在开发过程和后期维护过程中是必不可少的。每次在添加新类的时候都需要添加一些关于类的注释，包括创建时间、创建人、类的功能介绍、修改时间等一系列的信息，以方便以后的查找和快速了解。在Code Review过程中，良好的编码风格和合理的注释会有很大的帮助。

下面介绍一点我的编辑器中关于代码风格的配置和注释的配置.

1.关于类注释和方法注释：

类注释可以通过以下手段进行注释：

　　1）修改类模板的形式：

步骤如下：

　　a. 找到VS的安装路径，如:C:/vs2017,打开如下文件夹\Common7\IDE\ItemTemplates。可以看到文件夹下有这些文件模板：

如果你想对C#代码进行注释配置，打开CSharp\Code\2052，可以看到该文件夹下有class、Interface、WebClass等文件夹。打开class文件夹，

　　b.修改文件权限：class.cs文件(该文件就是创建一个C#类的模板)。我们需要先设置一下管理员账户才可以修改该类：右键该文件

 

 

给当前用户分配权限即可。

　　c.修改该类的内容，可以添加如下内容，当然可以进行对应的删减。该段内容我会放在文件的开始或者using引用之后。

#region << 版 本 注 释 >>
/*----------------------------------------------------------------
* 项目名称 ：$rootnamespace$
* 项目描述 ：
* 类 名 称 ：$safeitemname$
* 类 描 述 ：
* 所在的域 ：$userdomain$
* 命名空间 ：$rootnamespace$
* 机器名称 ：$machinename$ 
* CLR 版本 ：$clrversion$
* 作    者 ：$username$
* 创建时间 ：$time$
* 更新时间 ：$time$
* 版 本 号 ：v1.0.0.0
*******************************************************************
* Copyright @ $username$ $year$. All rights reserved.
*******************************************************************
//----------------------------------------------------------------*/
#endregion

 新建一个类文件尝试一下，效果如图所示：

 

注: 对于不同类型的项目文件类，要对该类型的项目文件类进行修改。如果我想修改一下ASP.NET Core的类，那么需要打开Common7\IDE\ItemTemplates\AspNetCore\Code\1033\Class。

　　2)使用code snippet的方式添加注释：

codesnippet 代码片段，就是使用自定义快捷键生成代码注释，也就是自定义一段代码片段，该方法可以用于类文件描述和方法描述上。步骤如下：

　　a. 创建代码片段：
　　在电脑的任意可访问的位置创建一个文件夹，如我在C:\VSSnippet,新建一个.snippet后缀的文件，一般文件名和你在VS中使用的快捷键名字对应。

　　

　　b.参照visual studio官网上关于code snippet的写法，编写代码片段。也可以直接去vs自带的代码片段中复制一份进行修改。

VS自带的代码片段位于：vs安装目录\VC#\Snippets\2052\Visual C#，我们可以复制一份cw.snippet文件到之前的文件夹下，并重命名为cm.snippet( create comments,该文件名可以随便写)

　　修改文件内容如下:

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
    <CodeSnippet Format="1.0.0">
        <Header>
            <Title>创建代码注释</Title>
            <Shortcut>cm</Shortcut>
            <Description>创建注释的代码片段</Description>
            <Author>King</Author>
            <SnippetTypes>
                <SnippetType>Expansion</SnippetType>
            </SnippetTypes>
        </Header>
        <Snippet>
            <Declarations>
                <Literal>
                    <ID>Description</ID>
                    <ToolTip>功能</ToolTip>
                     <Default>描述</Default>
                </Literal>
                <Literal>
                    <ID>Author</ID>
                    <ToolTip>作者</ToolTip>
                    <Default>King</Default>
                </Literal>
                <Literal>
                    <ID>CreateTime</ID>
                    <ToolTip>创建日期</ToolTip>
                     <Default>@@Today</Default>
                </Literal>
            
            </Declarations>
            <Code Language="csharp"><![CDATA[
            #region 创建描述
            /***
            *    功能描述: $Description$
            *    作    者: $Author$
            *    创建时间: $CreateTime$
            ***/
            #endregion
            $end$
            ]]>
            </Code>
        </Snippet>
    </CodeSnippet>
</CodeSnippets>

　　c. 在Visual Studio中应用代码片段

　　打开VS IDE，工具----> 代码片段管理(快捷键Ctrl + K, Ctrl + B),将刚创建的代码片段文件夹添加到代码片段管理器中。重启VS，在文件中是输入cm(在codesnippet中定义的<Shortcut>cm</Shortcut>)

 双击Tab键就可以插入代码片段了。

 

两种方式比较：

　　优点：

　　1.修改VS class模板的形式，该注释中可以包含很多信息。如作者、时间等信息

　　2.使用代码注释的形式，可以在类上添加注释，也可以在方法上添加注释。

　　不足：

　　1.修改VS class模板，只能在类创建的时候使用，并且不能在方法上添加注释、

　　2.使用代码注释的形式，有一些信息无法自动化处理，如时间等。当然可以使用VS 宏定义来定义函数，插入时间。

 提高代码质量插件：

CodeMaid : 可快速整理代码文件，清理不必要的代码和杂乱的格式。并在开发时实时提供代码复杂度的报告，以便帮助开发人员降低代码复杂度、提高代码质量。