代码写注释时的呢些讲究-Java-E先生的博客
Java
MySQL
大数据
Python
前端
黑科技
大语言模型
    首页 >> 互联网 >> Java

代码写注释时的呢些讲究

[导读]:代码写注释时的呢些讲究...
  1. 注释风格
  总述
  一般使用//或/**/,只要统一就好。
  说明
  //或/**/都可以,但团队要在如何注释及注释风格上确保统一。

  1. 文件注释
  总述
  在每一个文件开头加入版权、作者、时间等描述。
  文件注释描述了该文件的内容,如果一个文件只声明,或实现,或测试了一个对象,并且这个对象已经在它的声明处进行了详细的注释,那么就没必要再加上文件注释,除此之外的其他文件都需要文件注释。
  说明
  法律公告和作者信息:
  每个文件都应该包含许可证引用。也要为项目选择合适的许可证版本(比如,Apache 2.0,BSD,LGPL,GPL)。
  文件内容
  如果一个.h文件声明了多个概念,则文件注释应当对文件的内容做一个大致的说明,同时说明各概念之间的联系。一个一到两行的文件注释就足够了,对于每个概念的详细文档应当放在各个概念中,而不是文件注释中。
  不要在.h和.cc之间复制注释,这样的注释偏离了注释的实际意义。
  最后再举个最简单的实际例子:
/************************************************************************
*
*    Copyright  Copyright 2020 Google Inc.
*    File Name: 文件名
*    Description: 描述
*
*    Version: V1.0
*    Author: Your_Name
*    Create Time: 2021-06-28
*
*************************************************************************/

  1. 函数注释
  总述
  函数声明处的注释描述函数功能;定义处的注释描述函数实现。
  说明
  函数声明:
  基本上每个函数声明处前都应当加上注释,描述函数的功能和用途。只有在函数的功能简单而明显时才能省略这些注释(例如,简单的取值和设值函数)。
  比如:
/************************************************************************
*
*    函 数 名:函数名
*    函数功能:功能描述
*    输入参数:void
*    输出参数:void
*    返 回 值:  void
*
*    作    者:Your_Name
*    创建时间:2021-06-28
*    其他说明:无
*    修改信息:无
*
************************************************************************/
  函数定义:
  如果函数的实现过程中用到了很巧妙的方式,那么在函数定义处应当加上解释性的注释。比如,你所使用的编程技巧,实现的大致步骤,或解释如此实现的理由。举个例子,你可以说明为什么函数的前半部分要加锁而后半部分不需要。
  不要从.h文件或其他地方的函数声明处直接复制注释.简要重述函数功能是可以的,但注释重点要放在如何实现上。

  1. 变量注释
  总述
  通常变量名本身足以很好说明变量用途,某些情况下,也需要额外的注释说明。
  说明
  根据不同场景、不同修饰符,变量可以分为很多种类,总的来说变量分为全局变量、局部变量。
  一般来说局部变量仅限于局部范围,其含义相对简单容易理解,只需要简单注释即可。
  全局变量一般作用于多个文件,或者整个工程,因此,其含义相对更复杂,所以在注释的时候,最好描述清楚其具体含义,就是尽量全面描述。
  (提示:全局变量尽量少用)

  1. 拼写注释
  总述
  可能一个变量、一个函数包含的意思非常复杂,需要多个单词拼写而成,此时对拼写内容就需要详细注释。
  说明
  注释的通常写法是包含正确大小写和结尾句号的完整叙述性语句。大多数情况下,完整的句子比句子片段可读性更高。短一点的注释,比如代码行尾注释,可以随意点,但依然要注意风格的一致性。
  同时,注释中的拼写、逗号也很重要。虽然被别人指出该用分号时却用了逗号多少有些尴尬,但清晰易读的代码还是很重要的。正确的标点,拼写和语法对此会有很大帮助。

  1. TODO 注释
  总述
  对那些临时的,短期的解决方案,或已经够好但仍不完美的代码使用TODO注释。
  TODO注释要使用全大写的字符串TODO,在随后的圆括号里写上你的名字,邮件地址,bug ID,或其它身份标识和与这一TODO相关的issue。主要目的是让添加注释的人(也是可以请求提供更多细节的人)可根据规范的TODO格式进行查找。添加TODO注释并不一定意味着你要自己来修正,因此当你加上带有姓名的TODO时,一般都是写上自己的名字。

本文来自E先生的博客,如若转载,请注明出处:https://www.javajz.cn

留言区

联系人:
手   机:
内   容:
验证码:

历史留言

欢迎加Easy的QQ