[有效的注释]以及[文件风格]
以下为2014年底到2015年期间，自己认为的文件及注释应有的格式<部分区域已经做了修改和删减>
1 /************************************************************************* 2 *\CopyRight: 2015.9.21-NOW,Feel free to use and modify those codes. And 3 any modifications or copies shall remain these sentence for the purpose 4 of further development and code sharing. 5 *\Module/Sys: [M]/[S]Test 6 *\Version: 1.0.0.0 7 *\Description:Use for the describ of the functions of the file. 8 *\Author: CityForNaive 9 *\Date: 2015.9.21 10 *\History: <Date> <Dev> <Behavior> 11 *\ 2015.9.21 CityForNaive Build. 12 *************************************************************************/ 13 14 #pragma once /// Use this as first option. 15 16 #ifndef _COMMENT_H_ 17 #define _COMMENT_H_ 18 #endif // _COMMENT_H_ 19 20 #define _TEST_SUCCEED 1 /** Test succeed. */ 21 #define _TEST_PARTIAL_SUCCEED 2 /** Test partial succeed. */ 22 #define _TEST_FAILED 0 /** Test failed. */ 23 24 /** 25 *\Description:Use for the test functions. 26 *\Methods: 1.SetTester : Set the basic param of the test 27 2.GetTester : Get the result of a test. 28 *\Other: This is a C based class. 29 */ 30 class TestClass 31 : public TestBaseClass 32 { 33 public: 34 TestClass(void); 35 virtual ~TestClass(void); 36 37 public: 38 /** 39 *\Description:Set function for the test class. 40 *\Input: 1.const int& param1, the first param of the func. 41 2.const int& param2, the second param of the func. 42 *\Output: None. 43 *\Return: const int : _TEST_SUCCEED, succeed 44 _TEST_PARTIAL_SUCCEED, partial succeed 45 _TEST_FAILED, failed. 46 *\Other: None. 47 */ 48 const int SetTester(const int& param1, const int& param2); 49 50 /** 51 *\Description:Get the result of a test. 52 *\Input: 1.const int& token1, the first token of the func. 53 2.const int& token2, the second token of the func. 54 *\Output: 1.int& result, the result of the test. 55 *\Return: const int : _TEST_SUCCEED, succeed 56 _TEST_PARTIAL_SUCCEED, partial succeed 57 _TEST_FAILED, failed. 58 *\Other: None. 59 */ 60 const int GetTester(const int& token1, const int& token2, 61 int& result); 62 63 private: 64 int m_iParamFrst; /// The first param of the test. 65 int m_iParamScnd; /// The second param of the test. 66 }; // TestClass 67 68 /** Set function for the test class. */ 69 int TestClass::SetTester(const int& param1, const int& param2) 70 { 71 int rtnVal; // The return value of this function 72 rtnVal = _TEST_FAILED; 73 74 // Set the param of the test 75 if (param1 >= 0 && param2 >= 0) 76 { 77 rtnVal = _TEST_SUCCEED; 78 } 79 else if (param1 >= 0 || param2 >= 0) 80 { 81 rtnVal = _TEST_PARTIAL_SUCCEED; 82 } 83 else 84 { 85 rtnVal = _TEST_FAILED; 86 } 87 88 m_iParamFrst = param1; 89 m_iParamScnd = param2; 90 91 return rtnVal; 92 } 93 94 /** Get the result of a test. */ 95 int TestClass::GetTester(const int& token1, const int& token2, int& result) 96 { 97 int rtnVal; // The return value of this function 98 rtnVal = _TEST_FAILED; 99 100 // Judge the token to decide the result 101 if (token1 == m_iParamFrst && token2 == m_iParamScnd) 102 { 103 result = m_iParamFrst * m_iParamScnd; 104 rtnVal = _TEST_SUCCEED; 105 } 106 else if (token1 == m_iParamFrst || token2 == m_iParamScnd) 107 { 108 result = m_iParamFrst / m_iParamScnd; 109 rtnVal = _TEST_PARTIAL_SUCCEED; 110 } 111 else 112 { 113 result = 0; 114 rtnVal = _TEST_FAILED; 115 } 116 117 return rtnVal; 118 } 119 120 /// For interface that we just write the brief of the function. 121 122 class __declspec(novtable) ITestInterface 123 { 124 public: 125 /** This is a function of the interface. */ 126 virtual void func(const int& param, const char* charParam) = 0; 127 }; 128 129 /// here we can also use EXTERN_C instead of extern "C" if under VS. 130 extern "C" __declspec(dllexport) ITestInterface * getTestInterface();
(2021.12.4)之后呢，再回头看看当时写的东西，并不太实用——不符合多数时候的使用习惯。
首先，在文件头处理部分
1 #pragma once 2 #ifndef THISHEADER_H 3 #define THISHEADER_H 4 5 // TODO 6 7 #endif // !THISHEADER_H
其实，pragma once 跟宏定义防止重复做的是同一件事情，高版本的 pragma once 是完全能够满足需求的。当然，如果是做嵌入式或者单片机还是依赖宏定义——毕竟可靠性强。这里不必纠结风格问题，该用哪个用哪个。
函数注释部分
1 // \brief 获取对象示例并进行一定的初始化 2 // \param const string& 用于初始化的对象名 3 // \return WPAManager wpa的部分功能封装对象 4 // \notes 如果初始化失败则会返回空指针 5 static WPAManager& GetInstance(const string& strItem); 6 7 WPAManager& WPAManager::GetInstance(const string& strItem) 8 { 9 // 实际实现 10 }
自定义的注释很多地方不会被显示在函数名上，能用于visual studio 显示的只有寥寥的brief、param跟return，而且没用doxygen，如果采用doxygen规范会是另一个样子...
文件头部的注释除了需要特别申明版权及用途的一般是不加注释的——都有版本管理工具了谁还会在文件头写修改历史呢(如果是岛国躬匠那当我没说)
期间流程部分的注释，私以为进行逻辑处理时应该有一定的流程注释，变量名通过对应规则写好就是了，不用太纠结名称——但是需要符合规则，便于他人阅读。
名称部分
需要符合驼峰定义，testContent这种，一般不用简写；
m_开头为成员变量，g_开头为全局变量，_开头为系统变量(一般不会去定义)；
p修饰指针，c修饰产量，sz修饰字符、字符串，i修饰整形或其他数形，f修饰浮点float，d修饰浮点double，str修饰字符串string；
但是由上述规则会产生诸如，g_cszDefaultName、m_strCSSID这样的名称，虽然符合规则，但是输入查询的时候并不方便；
而如果把类型修饰滞后g_defaultName_csz、m_CSSID_str本身又不便于阅读，取舍之后还是选择前者。
函数名同上，开头大写即可，例如，GetCheckedCodes()。
文件分布
应该把__declspec()这种定义为宏扔到头部
1 #ifdef WPAMGR_EXPORTS 2 #define WPAMGR_API __declspec(dllexport) 3 #else 4 #define WPAMGR_API __declspec(dllimport) 5 #endif
这样做，自己的项目导出时定义这个FLG——项目设置里或者编译选项，则出场文件为对外的库文件，而使用者不会去定义它，则拿到时为导入库选项。(随便一个入门的人应该都知道这个)
而关于是否使用extern "C"众说纷纭。不过可以确定的是，采用C++的编译器确实会“因为链接时进行了重命名而导致函数名在不同版本时显现的不一致”，但是，这个情况是基于你需要面向多个版本实现单一功能时才需要的。
其一，你在公司做项目或者你自己的私人项目时，确定的编译环境不会带来这个问题——除非你非常欠打把C++的编译库扔给C用。
其二，真的遇到了这个问题，统一一下C++的版本就可以了，并不是什么大问题——看个人编写习惯，如果非常依赖一些旧标准就会是个大问题。
其三，C++有的开源库是只有头文件的，利用.hpp自动内联的方式，把实现直接扔进了头文件里，基本上可以忽略版本的影响。
