visual studio (2019) c/c++ 添加自定义代码片段+注释

visual studio (2019) c/c++ 添加自定义代码片段（注释自动生成小技巧）

前言

最近需要参与 C/C++ 项目的开发，使用 visual studio 2019 IDE 作为开发工具。在编写调试代码的过程中，发现同事大多通篇代码，几乎没有任何注释（大牛级别的），这让我很是困扰：没有注释并且不加讲解的代码会使合作开发者花费更多的精力去解读双方的代码功能从而分配更少的时间在项目编码上，极大的影响开发效率，我认为是不可取的。

研究了一下发现，这也是 visual studio IDE 自动注释功能不人性化的一个副作用。vs 没有 vscode 那样丰富的插件（大多数都是免费的），网上阅览的一些插件教程，比如 whole tomato 的 vs assist 虽然可以破解，但毕竟收费，用着憋屈。

好在 visual studio 有一个工具 --> 代码片段管理功能，可以让我们预先自定义一个代码片段：常用的功能语句、常用的函数或者常用的注释，然后在编写代码的时候通过预先定义的关键词引出代码片段，再用tab键在代码中补全/添加这个片段。

具体操作

具体的操作如下

1. 在 vs2019 中依次选择 工具 --> 代码片段管理器 ，点击打开管理器窗口
   
   选择 Visual C++（我现在使用的语言，操作方法对其他语言兼容），然后复制注释2中的地址并在文件资源管理器中定义到此地址，关闭代码片段管理器，资源管理器中的文件如下：
   
2. 现在开始编写自定义的代码片段。在这之前，可以用 notepad++ 查看这些.snippet代码片段的语法格式，然后通过复制 --> 粘贴 --> 重命名的方式创建新的代码片段（在这个文件目录中只能创建文件夹，无法重建文件）。现在通过这种方式，我创建了三个代码注释片段，名字依次为header.snippet，fnote.snippet，note.snippet。

header.snippet

每一个源程序.cpp的起始注释，注明代码编写者等相关信息以及历史迭代信息。注意xml 文件中的 <Title>与<Shortcut>标签，Shortcut设置成代码片段引用快捷键关键字，当在编译器中敲击这个关键字后，会弹出Title名称的代码片段提示，敲击Tab可以插入片段

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets >
  <CodeSnippet Format="1.0.0">
    <Header>
      <Title>header</Title>
      <Shortcut>header</Shortcut>
	  <Description>give header infomation</Description>
    </Header>
    <Snippet>
      <Code Language="cpp">
        <![CDATA[
///****************************************************************************
/// @author  : Jacob_Lee                                                         
/// @date    :                                                                 
/// @file    :                                                                 
/// @brief   :                                                                 
///----------------------------------------------------------------------------
///                           Change History                                   
///----------------------------------------------------------------------------
///                              
///****************************************************************************
            ]]>
      </Code>
    </Snippet>
  </CodeSnippet>
</CodeSnippets>

fnote.snippet

函数功能注释，注明函数的数据、输入、输出以及简要说明。

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets >
  <CodeSnippet Format="1.0.0">
    <Header>
      <Title>fnote</Title>
      <Shortcut>fnote</Shortcut>
	  <Description>function note</Description>
    </Header>
    <Snippet>
      <Code Language="cpp">
        <![CDATA[
///****************************************************************************
/// @data    :                                                                 
/// @input   :                                                                 
/// @output  :                                                                 
/// @brief   :                                                                 
///****************************************************************************
            ]]>
      </Code>
    </Snippet>
  </CodeSnippet>
</CodeSnippets>

note.snippet

一般性说明代码片段

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets >
  <CodeSnippet Format="1.0.0">
    <Header>
      <Title>gnote</Title>
      <Shortcut>gnote</Shortcut>
	  <Description>general note</Description>
    </Header>
    <Snippet>
      <Code Language="cpp">
        <![CDATA[
///****************************************************************************                 
/// @brief   :                                                                 
///****************************************************************************
            ]]>
      </Code>
    </Snippet>
  </CodeSnippet>
</CodeSnippets>

3. 在编写完自定义代码片段后，重启 visual studio 2019。点击工具 --> 代码片段管理验证新添加的代码片段，添加成功，如图：
   
4. 在编译器中插入代码片段，例如header片段，如图：
   

需要完善的

注释应该统一化，标准化，这样才可以方便不同的背景的开发人员阅读，接下来需要参考比如 Google，Doxygen 的注释规范对自定义的代码片段进行优化。

参考

1. 链接: VS中如何添加自定义代码片段——偷懒小技巧.
2. 链接: 是不是晚了点：Visual Studio可以自动生成注释啦（这个有点坑，doxygen 安装了但是快捷键调不出来，还是贴出来以供参考）.
3. 链接: Doxygen的安装与配置及简单注释规范.
4. 链接: Doxygen和VS助手配置代码注释模板
5. 链接: Doxygen and Visual Studio（教你如何安装 doxygen）
6. 链接: Doxygen and XML Doc Comment support（看着眼馋但就是调不出 doxygen 自动注释功能）
7. 链接: Getting Doxygen.
8. 链接: Intellisense not working with doxygen comment style（doygen bug）.