当你阅读别人的代码时如果没有注释那会是件比较痛苦的事.一说到注释我们马上想到是通过//或/* */这样来添加一些描述信息.这只是狭义的注释.
广义的注释我们可以理解为,任何有助于理解代码的信息都可以看成注释.
我们可以把写代码和写文章类比下.自然语言会有词法,句法,语义这几个概念.代码中的语法和句法就相当于一个编程语言中的基本语法规范.这是我们学习一门编程语言必须掌握的.所以注释的时候一般不会涉及到这些信息.
注释主要涉及到语义的描述.语义从大的方向,软件产品面向的应用来说,就是要解决的问题本身的逻辑,如果是些应用软件也可以叫业务逻辑.我们把业务逻辑理清头绪后就会来个啥数据建模之类的.然后写设计文档之类的,有啥概要设计与详细设计,这些文档可以看成非常重要的注释.
然后就是写到代码里的注释了,通过//或/* */标识出来.还有一种注释叫自我注释,就是通过函数或变量名字就得得到一些有用的信息
这里主要讲下用//或/* */做的注释
用// 还是/* */就看你自己的偏好了.最重要的是保持一致,就是在一个项目中大家达成一致,全部用哪一种或者在某个地方用//,另外的地方用/* */
注释的位置及常见内容
1.文件注释
在C++的代码都是分布在一个个的头文件和源文件中,如果是用的VS则是h后缀文件和cpp后缀文件. 当然了有时你用以内联函数还可能会有inl文件.每个文件的开头部分你可以添加注释信息.
内容一般是:版权,作者,编写日期,功能描述.例如
/**************************************************************************
Copyright:MyCompany
Author: Arwen
Date:2013-01-09
Description:Provide functions to connect Oracle
**************************************************************************/
或者
//Copyright:MyCompany
//Author: Arwen
//Date:2013-01-09
//Description:Provide functions to connect Oracle
有时如果修改了代码,还可以添加修改人,日期,修改内容有目的这些信息.
2.类注释
一般是简单的说下这个类的功能,如果你在文件开头已经描述了这里也可以省略.如果要注释的话就可以这样简单的描述下.
// COleDataObject -- simple wrapper for IDataObject
class COleDataObject
{
}
或者
/*COleDataObject -- simple wrapper for IDataObject*/
3.函数注释
描述函数的功能及参数,其他相关信息.例如
//Summary: connect the database
//Parameters:
//connInfo:A class contains the connect info ,such as user name ,pwd,etc.
// directConnect : use TNS name or use direct connection info
//Return : true is connect successfully.
bool ConnectDatabase(ConnectInfo connInfo, bool directConnect);
或者
/*
*Summary: connect the database
*Parameters:
* connInfo:A class contains the connect info ,such as user name ,pwd,etc.*
* directConnect : use TNS name or use direct connection info
*Return : true is connect successfully.
*/
4.变量注释
一个变量如果代表的意思不容易从变量名看出来,而且又挺重要的话最好也加点注释.例如
UINT m_nGrowBy; // number of cache elements to grow by for new allocs
或者
UINT m_nGrowBy; /* number of cache elements to grow by for new allocs*/
5.实现注释
在一些逻辑性很强,不容易理解的代码块前添加注释.特别是是像一些算法,看起来就几行,但想个半天都未必明白到底是啥意思来着.
例如
// copy elements into the empty space
while (nCount--)
m_pData[nIndex++] = newElement;
还有就是如果想针对函数的某些个参数做些注释,那最好把参数分几行写.
void MyFunction(string name, //This is my name
int age)
另外有时一个函数很长,里面有奶多个大括号{ } ,这样一嵌套,有时你不知道谁对应谁了,你要往里面插入代码就容易出错.你也可以在些结尾的大括号加个注释,表明它是哪个if或while语句的结束处.
在C#中是可以通过#region 加 #endregion 来做注释.同时开发环境VS能提供支持让你方便的折叠这样注释的代码.
VS也支持在C++中通过#pragma region 与
#pragma endregion 来做注释,但这在其它编译器中不会被识别,所以需要考虑到跨平台的话或者会使用不同的编译器的话就最好别用.
6.TODO 注释
todo的意思就是待做的事.比如你代码写了一半,然后下班了.为了方便你第二天很快的找到那具体地方,或者防止你忘记.就可以用todo注释下.因为一些开发环境提供了对它的支持,可以让你方便的找到哪些个地方有todo注释,起个书签的作用.你选View-->Task List,然后在下面的下拉列表中选择comments就会列出所有TODO注释信息.
另外你也可以写个TODO留着以后实现那功能也行,注释信息一般可以写上你的名字和邮箱,然后说下待实现的功能或其他事项
分享到:
相关推荐
华为代码规范,适用 C/C++ 1 概述 ................................................................................................................................................................... 5 ...
C++编码规范,用于软件企业内部非常适用,采用该规范写出的代码易读易懂,从命名上就能看出很多东西,不用再用繁索的注释来进行注释了~
对C++文件进行编码规范检查,输出代码行数和注释行数。
如果每个项目将代码置于不同命名空间中,project1::Foo和project2::Foo作为不同符号自然不会冲突。 缺点:命名空间具有迷惑性,因为它们和类一样提供了额外的(可嵌套的)命名轴线。在头文件中使用不具名的空间容易...
google c++ 编码规范,详细注明了C++写代码过程中一些注意的问题,命名规范,注释规范等等。
本标准系公司首次发布实施,主要针对公司所有软件产品源代码范围的 C 和 C++编码风格,对 C 和 C++文件的版式、注释、标识符命名、可读性、变量、结构、函数和过程等方面均作出规范,以保障公司项目代码的易维护性和...
我终选择了编码规范。 编码规范是什么? 简单说——编码规范是一种…规范。通过建立起一种通用的约定和模式,所有人都遵循,以此帮助打造健壮的软件。 使用编码规范有什么好处? 有很多好处,包括(不...
微软内部员工写的.net编码规范 本文档描述了微软一站式代码示例库项目组所采纳的关于本地 C++ 和 .NET (C# 和VB.NET)代码的编程风格指导规范 1 概览 1 1.1 原则和主旨 1 1.2 术语 2 2 通用编程规范 3 2.1 明确和...
本实验可基于 Visual Studio Code 等平台开发,参考主流的编码规范,如 Google C++Style 二、Guide(中文版) 2.1 编程语言和开发工具 编程语言: ANSI C/C++ 开发工具: Visual Studio Code、Dev C++ 2.1 编码...
Google的c++编码规范,主要是关于代码编写的规范,如命名规范,注释规范等
JavaScript是一种语法灵活,简单易懂的脚本语言。正因为灵活,因此很多人在...此编码规范融合了多位程序员的编程经验,适用于开发和维护期间,发布代码时可以用工具进行优化处理,剔除注释和空格字符,以提高执行效率。
1. 设计一个学生类student,包括学生学号、姓名、成绩;设计一个友元函数,比较某两个学生成绩的...编制一个程序,度量由用户指定的、严格按照C++编码规范编写的C++源文件的代码规模,分别输出代码行数和注释行数。
c++实现的多叉树,文件里面有文档,操作说明。代码有注释,基本按照编码规范来的。
1. 设计一个学生类student,包括学生学号、姓名、成绩;设计一个友元函数,比较某两个学生成绩的...编制一个程序,度量由用户指定的、严格按照C++编码规范编写的C++源文件的代码规模,分别输出代码行数和注释行数。
3 二、设计目的与任务 1 1、本课程设计的目的 1)通过课程设计更进一步理解C++的基础知识和面向对象的思想。 2)训练用系统的观点和软件开发一般规范进行软件开发,并在此过程中培养严谨的 科学态度和良好的工作...
别的不多说了 非常好的东西 等待有缘人 摘录目录如下 Google C++ 风格指南 - 中文版 目录 译者前言 背景 1. 头文件 1.1. #define 保护 ...9.1. 现有不合规范的代码 9.2. Windows 代码 10. 结束语
在研究项目团队协作开发的情况下(这里的团队协作也适合于应用项目...本规范由程序风格、命名规范、注释规范、程序健壮性、可移植性、错误处理以及软件的模块化规范等部分组成。 本软件开发规范适合讨论C/C++程序设计。
书中深入地分析了开发不包含逻辑和语法错误的代码技巧以及调试程序的基本原理,介绍了开发和调试命令行代码的过程和方法,说明了关于定位、分析及修复编程错误的方法,介绍了开发 Visual C++程序时所遇到的特殊...
2.可读性:代码编写是否规范,是否便于阅读。如函数、变量命名,‘{ }’的缩进,关键位置适量注释等 3.功能的完善:除要求实现的功能外,完成了其它的功能,实现了功能的完善 4.健壮性:异常处理的情况 5.界面的设计...