关于搭建一个标准代码仓库的一些tips

​ 所谓大学，就是大不了自己学。自从大一开始接触编程，所有的c++、python以及开发技巧都是自己零零碎碎拼凑而来的知识，就这样一直跌跌撞撞走到大三。现在希望将所学到的一些关于建立标准代码仓库的tips记录下来，希望能够帮助到更多的初学者。

README.md

​ 我们在创建github项目的时候，常常看见github强烈推荐我们创建一份readme文件。一份简要清晰的readme，不仅能够让开发者在最短时间回想起开发要点，也是能够最快地帮助别人了解你的代码仓库信息。所以，写好一份简要清晰的readme文件，是开发一个标准代码仓库必不可少的。

​ 关于readme文件的编写，我推荐按照Github开源项目中的Standard Readme标准来书写，这个 README 标准是由 RichardLitt 发起，十多名开发者共同贡献完成的，在 GitHub 上有 1230+ Star。根据项目中默认最简要的格式，可以按照以下格式来书写：

Table of Contents

• Install
• Usage
• Maintainers
• Contributing
• License

Install

Usage

Maintainers

@Rosen

Contributing

PRs accepted.

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT © year full-name

LICENSE

​ License 是软件的授权许可，里面详尽表述了你获得代码后拥有的权利，可以对别人的作品进行何种操作，何种操作又是被禁止的。软件协议可分为开源和商业，本文只讨论开原协议。下面用一张图说明各种License的含义。

​ 开放源代码许可协议更容易为他人作出贡献，而不必寻求特别的许可。它也可以保护你作为原创者的权利，至少确认了你的贡献，它还可以保证你的工作不为别人所剽窃。

​ 关于License的内容在网上可以直接获取到，下面是常用的MIT许可证的具体内容：

Copyright <YEAR> <COPYRIGHT HOLDER>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

.clang-format

​ Clang-Format可用于格式化（排版）多种不同语言的代码，其自带的排版格式主要有：LLVM, Google, Chromium, Mozilla, WebKit。在clion、vscode等常用的IDE中都有相应的Clang-Format格式化工具，使用Clang-Format可以在多个协作者开发时，也能够保证代码格式的统一，只需要通过一个快捷键，即可完成对代码的自动格式化。

​ 在vscode中，Ubuntu下格式化快捷键：Ctrl+Shift+I，Windows下格式化快捷键：Shift+Alt+F。

​ 下面是笔者根据本人喜好设置的.clang-format，有需要的可以自取。

---
BasedOnStyle:  Google
ColumnLimit:    120
MaxEmptyLinesToKeep: 1
# 允许排序#include
SortIncludes: false# 标准: Cpp03, Cpp11, Auto
Standard:        Auto
IndentWidth:     4
# tab宽度
TabWidth:        4
# 使用tab字符: Never, ForIndentation, ForContinuationAndIndentation, Always
UseTab:          Never# 访问说明符(public、private等)的偏移
AccessModifierOffset: -4
# 构造函数的初始化列表的缩进宽度
ConstructorInitializerIndentWidth: 4
# 延续的行的缩进宽度
ContinuationIndentWidth: 4
# 缩进case标签
IndentCaseLabels: true
IndentFunctionDeclarationAfterType: false
# 左对齐逃脱换行(使用反斜杠换行)的反斜杠
AlignEscapedNewlinesLeft: false
# 对齐连续的尾随的注释
AlignTrailingComments: true# 允许函数声明的所有参数在放在下一行
AllowAllParametersOfDeclarationOnNextLine: false
# 自动检测函数的调用和定义是否被格式为每行一个参数(Experimental)
ExperimentalAutoDetectBinPacking: false
# 在ObjC的protocol列表前添加一个空格
ObjCSpaceBeforeProtocolList: true
# 去除C++11的列表初始化的大括号{后和}前的空格
Cpp11BracedListStyle: false# 允许短的块放在同一行
AllowShortBlocksOnASingleLine: true
# 允许短的if语句保持在同一行
AllowShortIfStatementsOnASingleLine: false
# 允许短的循环保持在同一行
AllowShortLoopsOnASingleLine: false
# 允许短的函数放在同一行
AllowShortFunctionsOnASingleLine: None
# 允许短的case标签放在同一行
AllowShortCaseLabelsOnASingleLine: false
# 总是在template声明后换行
AlwaysBreakTemplateDeclarations: true
# 总是在多行string字面量前换行
AlwaysBreakBeforeMultilineStrings: false# 在二元运算符前换行
BreakBeforeBinaryOperators: false
# 在三元运算符前换行
BreakBeforeTernaryOperators: false
# 在构造函数的初始化列表的逗号前换行
BreakConstructorInitializersBeforeComma: true# false表示所有形参要么都在同一行，要么都各自一行
BinPackParameters: true
# 构造函数的初始化列表要么都在同一行，要么都各自一行
ConstructorInitializerAllOnOneLineOrOnePerLine: true
# 继承最常用的指针和引用的对齐方式
DerivePointerBinding: falsePointerBindsToType: true# 命名空间的缩进: None, Inner(缩进嵌套的命名空间中的内容), All
NamespaceIndentation:	All# 对于每个在行字符数限制之外的字符的penalty
PenaltyExcessCharacter: 50
# 在call(后对函数调用换行的penalty
PenaltyBreakBeforeFirstCallParameter: 30
# 在一个注释中引入换行的penalty
PenaltyBreakComment: 1000
# 第一次在<<前换行的penalty
PenaltyBreakFirstLessLess: 10
# 在一个字符串字面量中引入换行的penalty
PenaltyBreakString: 100
# 将函数的返回类型放到它自己的行的penalty
PenaltyReturnTypeOnItsOwnLine: 50# 在尾随的评论前添加的空格数
SpacesBeforeTrailingComments: 4
# 在圆括号的(后和)前添加空格
SpacesInParentheses: false
# 在尖括号的<后和>前添加空格
SpacesInAngles:  false
# 在空的圆括号中添加空格
SpaceInEmptyParentheses: false
SpacesInCStyleCastParentheses: false
# 在C风格类型转换后添加空格
SpaceAfterCStyleCast: false
SpaceAfterControlStatementKeyword: true
# 在赋值运算符之前添加空格
SpaceBeforeAssignmentOperators: true# 在大括号前换行: Attach(始终将大括号附加到周围的上下文), Linux(除函数、命名空间和类定义，与Attach类似), 
#   Mozilla(除枚举、函数、记录定义，与Attach类似), Stroustrup(除函数定义、catch、else，与Attach类似), 
#   Allman(总是在大括号前换行), GNU(总是在大括号前换行，并对于控制语句的大括号增加额外的缩进), WebKit(在函数前换行), Custom
#   注：这里认为语句块也属于函数
BreakBeforeBraces: Custom# 大括号换行，只有当BreakBeforeBraces设置为Custom时才有效
BraceWrapping:AfterCaseLabel: true# class定义后面AfterClass: true# 控制语句后面AfterControlStatement: true# enum定义后面AfterEnum: true# 函数定义后面AfterFunction: true# 命名空间定义后面AfterNamespace: true# struct定义后面AfterStruct: true# union定义后面AfterUnion: true# catch之前BeforeCatch: true# else之前BeforeElse: trueIndentBraces: false
...

Doxygen 代码注释风格

​ Doxygen其实是一个程序的文档产生工具，可以将程序中的注释转换成说明文档或者说是API参考手册，从而减少程序员整理文档的时间。当然这里程序中的注释需要遵循一定的规则书写，才能让Doxygen识别和转化。因此，以Doxygen 为风格的代码注释是最为常见的一种格式。

Ubuntu下安装Doxygen

sudo apt-get install graphviz
sudo apt-get install doxygen
# 带gui的doxygen
sudo apt-get install graphviz-gui

代码注释风格

• 文件信息
  • @file 文件名(遵守文件命名规则) --> 文件声明，即当前文件名
  • @author 作者名 --> 作者
  • @version 版本号 --> 版本号
  • @todo 说明文字 --> TODO 列表，在相关页面有它专门一项
    注:只能在实现文件(.c/.cpp)中使用，
    　 　 如果相同函数的实现文件与头文件中均有,生成的文档中会有重复项，
    　 　 可以理解为调用者不应知道实现流程。
  • @date 日期时间 --> 说明文件生成的日期时间
  • @section 章节标题 --> @section LICENSE 版权许可 @section DESCRIPTION 描述
• 模块信息
  • @defgroup 模块名(英文) 显示名(中文) @{ 类/函数/变量/宏/… @}–> 定义模块
  • @ingroup 模块名(英文) [显示名(中文)]–> 作为指定名的模块的子模块,显示名为可选项,
    可与指定名的模块的显示名不同。
  • @addtogroup 模块名(英文) [显示名(中文)] --> 作为指定名的模块的成员,显示名为可选项,
    必需与指定名的模块的显示名相同。
  • @name 显示名(中文) @{ 变量/宏 @} --> 按用途分,以便理解全局变量/宏的用途
• 函数信息
  • @param[in] 参数名 说明文字 --> 输入参数
    @param[out] 参数名 说明文字 --> 输出参数
    @param[in,out] 参数名 说明文字 --> 即输入又输出参数
  • @arg 参数/返回值 说明文字 --> 以列表形式说明参数取值意义
  • @return 说明文字 --> 返回值说明
  • @retval 说明文字 --> 特定返回值说明
  • @note 说明文字 --> 注解,可以描述工作流程和注意事项
  • @par [段落标题] --> 开创新段落,一般与示例代码联用
  • @code --> 示例代码开始
  • @endcode --> 示例代码结束
  • @see 类/函数/变量/文件/URL --> 参见,
    类名::函数名 或 ::函数名 可以变成超链接点击跳转到对应函数说明处
    　 函数重载的情况下,要带上参数列表以及返回值
  • @deprecated 说明文字 --> 过时列表,在相关页面有它专门一项,
    　 注:只能在头文件(*.h)中使用,如果相同函数的实现文件与头文件中均有,
    　 　 生成的文档中会有重复项,可以理解为维护者不关心这个接口是不是要过时。
  • @pre 说明文字 --> 前置条件
• 提醒信息
  • @brief 说明文字 --> 摘要,即当前文件/函数说明
  • @attention 说明文字 --> 注意
  • @bug 说明文字 --> 问题
  • @warning 说明文字 --> 警告

Doxygen生成文档

1. 生成配置文件

# 默认配置文件名为：Doxyfile
doxygen -g <config-file>
# 或（不含注释）doxygen -s -g <config-file>

2. 修改配置文件

   其中包括项目编码、项目名称、版本号、logo、输入编码等选项

3. 按照Doxygen注释风格编程

4. 生成文档

doxygen <config-file>

​ 完成后，可以在生成的html文件夹中的见到index.html文件，打开后即可看到生成的项目信息页面。