[有效的注释]以及[文件风格]
以下为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自动内联的方式,把实现直接扔进了头文件里,基本上可以忽略版本的影响。
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 没有源码,如何修改代码逻辑?
· 一个奇形怪状的面试题:Bean中的CHM要不要加volatile?
· [.NET]调用本地 Deepseek 模型
· 一个费力不讨好的项目,让我损失了近一半的绩效!
· .NET Core 托管堆内存泄露/CPU异常的常见思路
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· 没有源码,如何修改代码逻辑?
· PowerShell开发游戏 · 打蜜蜂
· 在鹅厂做java开发是什么体验
· WPF到Web的无缝过渡:英雄联盟客户端的OpenSilver迁移实战