精华内容
下载资源
问答
  • 包含图片转字符画工具(jave5)、原理图转字符画工具(AACircuit1_28_7)。使用方法可以查询对应名字
  • 代码注释生成文档工具,带有demo,对于文档的生成维护很有帮助
  • Java代码注释模板

    2017-09-18 16:10:22
    为便于规范各位开发人员代码、提高代码质量,研发中心需要启动代码评审机制。为了加快代码评审的速度,减少不必要的时间,可以加入一些代码评审的静态检查工具,另外需要为研发中心配置统一的编码模板和代码格式化...
  • Eclipse 代码注释模板

    2018-12-18 10:26:28
    Eclipse 代码注释模板 Eclipse 代码注释模板 Eclipse 代码注释模板 Eclipse 代码注释模板
  • java代码注释规范文档

    2018-09-18 10:33:34
    后端开发技术的代码注释规范 单行注释 多行注释 块注释 文档注释 标签注释等等
  • 清除Java代码注释

    2016-12-26 22:53:27
    1、使用MyEclipse清除注释 2、使用项目工程清除注释 3、简单方便操作 4、代码共享 ..
  • git提交代码注释规范

    2018-01-12 16:24:01
    git提交代码注释规范、git提交常用操作的规范指南、[A] 新增 :(新加入的需求) [M] 修改 :( 修改或者重构代码) [D] 删除 :(删除多余的文件 ) [F] 修复 :(修复bug)
  • Java代码注释率检查器
  • 本资源包含完整的谷歌开源激光slam算法:cartographer,并对其中各部分代码详细注释,使初学者能够尽快上手阅读以及学习该方法,注释如有错误,还请联系交流指出!
  • 阿里巴巴内部 代码格式化规范xml,code 导入XML 。 阿里巴巴内部 代码格式化规范xml,code 导入XML 阿里巴巴内部 代码格式化规范xml,code 导入XML 阿里巴巴内部 代码格式化规范xml,code 导入XML 阿里巴巴内部...
  • Doxygen代码注释规范

    2015-02-06 16:30:45
    自己的编写的Doxygen代码注释规范,包括安装、使用和规范,很详细。可以直接生成.chm格式的注释文档,对于大型程序开发很有帮助。
  • 代码注释比统计工具

    2014-05-26 15:49:57
    1、显示各个文件详细注释情况及比例值; 2、汇总各个所有统计结果; 3、图形显示汇总结果情况;
  • 对YOLOV3的核心代码进行了注释注释量大约上万行,有兴趣的小伙伴可以拿去研究研究或者继续注释
  • 代码注释删除工具

    2013-05-10 11:24:39
    不想让非授权者查看软件源代码注释信息或者敏感信息,即使源代码被获取也无法正确理解代码的核心思想。
  • 这几天,红警1的开源代码重现江湖,这个20年前,甚至25年前的代码,被我们所有的后来者所惊叹,这才是一个艺术品一般的存在。...本文将讲述3个编码时需要注意的部分,并着重讲解如何编写出规范的代码注释并加以利用。

    1.前言

    这几天,红警1的开源代码重现江湖,这个20年前,甚至25年前的代码,被我们所有的后来者所惊叹,这才是一个艺术品(art)一般的存在。其优秀的代码才是一款RTS游戏能够风靡全球的最根本保障。
    其开源链接为:https://github.com/electronicarts/CnC_Remastered_Collection
    如果你想重温这款童年记忆,那么花费140人民币,你就可以在Steam上体验到这款游戏。

    但是,我们的重点,主要在其代码上,因此不放出其游戏截图了,而是专注代码。下面是我随便点开的一个文件内容。大家可以欣赏一下什么是赏心悦目的代码。
    在这里插入图片描述
    在这里插入图片描述
    在这里插入图片描述

    2. 我们惊叹它的什么?

    通过上图,我们能够看到什么?我们惊叹的是它的什么?
    先看看小伙伴们的评价(只摘取了部分评价):
    在这里插入图片描述

    在这里插入图片描述
    在这里插入图片描述
    在这里插入图片描述
    在我看来,我们惊艳的部分至少包含三点:

    1. 清晰的代码注释
    2. 语义化的编码规范
    3. 小而精的逻辑实现

    2.1 清晰的代码注释

    我们可以看到非常工整的文档头注释(图1),还有详细的方法注释(图2),以及代码的字里行间里的逻辑注释(图3)。这些注释不仅仅是简单的重复代码,更把代码背后的业务逻辑详细的呈现了出来,使得我们不用猜测这个的用途,只读代码就可以知道它应该在哪里使用。最为夸张的是第三张,在具体实现中,注释竟然比代码所占篇幅还要大。

    2.2 语义化的编码规范

    我们可以看到它明显的语义化编码,也就是在逻辑实现部分,尽可能的能够少考虑具体的实现,如if判断条件中,使用一个函数来实现具体的判断,而不是直接把判断细节暴露出来。这有助于我们思维的连续性,从而从更高的层面对于代码有一个整体的把握。

    2.3 小而精的逻辑实现

    一般的,尽可能的要让一个函数的实现少,大概一个屏幕可以放得下即可,真正做到一个函数只做1件事,这样既可以避免逻辑混乱,而且也易于维护。对于其中的复杂的逻辑的细节实现,完全可以放到另一个函数中,从而避免一个函数包含了若干个层次的逻辑。

    3. 依葫芦画瓢

    那么在我们感叹之余,我们能不能做些什么向大佬看齐?在我的Blink发出以后,收到了上百个点赞评论,一致认为都想像20多年前的前辈一样优雅的编程。那么,我们就从最简单的、最明显改观的代码注释开始。

    在Python中,代码注释其实就两种,单行代码注释(#)和多行代码注释("""""")。但是我们需要用到的地方则有4个部分:文档级、类级、方法级和行级别。下面我们分别讲解一下这些部分的组成。

    3.1 添加文档级注释

    我们可以看到红警文件开头的那个非常醒目的注释,它展示了整个文件的简要信息,如属于什么项目,谁在什么时候创建的,什么时候更新的,而且以一种非常规范的格式呈现在我们面前。我们能不能拥有这样酷炫的文档开头呢?答案是Yes!
    首先看一下我复现的效果:
    在这里插入图片描述
    尽管看起来可能没有红警原版霸气,但是只要学会了这个技术,我们都可以创建属于自己的风格的文件头。我们只需要利用pycharm中的文件模板设置即可。它总共分为3个步骤:
    首先,点击File->Settings进入设置界面,选择Editor下的File and Code Templates选项。
    在这里插入图片描述
    然后,点击Python Script(你也可以为其他类型文件设置文件头),就可以看到最右侧显式的文件模板了。
    最后,只需要将我们喜欢的文件头复制粘贴进去即可,点击OK即可。

    下面是我仿照红警风格自己设计的文件头,大家可以随意取用(CV一下):

    #!/usr/bin/env python
    # encoding: utf-8
    '''
    #-------------------------------------------------------------------#
    #                   CONFIDENTIAL --- CUSTOM STUDIOS                 #     
    #-------------------------------------------------------------------#
    #                                                                   #
    #                   @Project Name : ${PROJECT_NAME}                 #
    #                                                                   #
    #                   @File Name    : ${NAME}.py                      #
    #                                                                   #
    #                   @Programmer   : Adam                            #
    #                                                                   #  
    #                   @Start Date   : ${DATE} ${TIME}                 #
    #                                                                   #
    #                   @Last Update  : ${DATE} ${TIME}                 #
    #                                                                   #
    #-------------------------------------------------------------------#
    # Classes:                                                          #
    #                                                                   #
    #-------------------------------------------------------------------#
    '''
    

    当然,更多其他的这种内置变量或者自定义变量的使用方法可以参见《详解pycharm新建文件时头部的模板》。

    3.2 添加类级注释

    当添加完文件注释以后,我们就需要添加更加细致的注释,首先来看对于类的注释。下面的例子给出了类注释的两个部分,一个部分是直接处于类下的简要介绍,另一个则是在__init__下的注释。两个部分都是使用"""进行标记的。图上风格为pycharm自带的编码风格,也有google和Numpy风格的注释,详情可以看《python常见的三种注释风格

    class CustomFile:
        """
        This is the main class, the file contains all documents.
        One document contains paragraphs that have several sentences.
        It loads the original file and converts the original file to new content.
        Then the new content will be saved by this class.
        """
        def __init__(self,src_file_name:str):
            """
            Initial the custom file by src file.
            :param src_file_name: string, the original filename.
            :return: None
            """
            file = open(src_file_name, encoding='utf-8').read()
            file="<File>"+file+"</File>"    # Special operation to avoid there is no root. node in original file.
            self.soup = BeautifulSoup(file, 'xml')
            self.document_list=[]
            self._set_documents()
    

    3.3 添加方法级注释

    更加细致的注释是在方法级的注释,如下面代码所示,它注释在方法上,一个好处是可以直接指导这个函数的功能,另一个好处就是当你在查看方法时,不需要点击方法里面查看源代码,也知道它的用途、参数和返回值,这个操作我们下面会介绍。

    def to_string(self):
            """
            Convert the document into string.
            :return: string, example: para\n\npara\n\npara
            """
            paragraph_string_list=[]
            for paragraph in self.paragraph_list:
                paragraph_string_list.append(paragraph.to_string())
            result="\n\n".join(paragraph_string_list)
            return result
    

    3.4 添加行级注释

    最细致的是行级注释,只注释在每一个行上,例如刚才出现过的例子。它可以用来解释一些不是很容易知道操作的目的的代码。

    file="<File>"+file+"</File>"    # Special operation to avoid there is no root.
    

    3.5 其他小技巧

    经过以上4级的注释,我们让代码更加的丰满了,从而能够达到红警里注释的效果。但是我们这东西可不是绣花枕,中看不中用,它是可以实实在在帮助我们提高编程效率的。下面我们介绍一些小技巧来帮助我们更好的利用我们/其他人的注释。

    3.5.1 查看方法注释

    当我们费了千辛万苦注释完毕后,该怎么查看呢?一个方法就是将鼠标放置在我们想要查看的方法上,按住ctrl,就可以查看到其注释了。
    在这里插入图片描述
    另一个方法则是ctrl+Q,它用来查看说明文档呈现的注释,两者的不同大家可以通过下面的图和上面的图对比可得。
    在这里插入图片描述

    3.5.2 生成说明文档

    就像刚才讲的,这些都是在代码里查看的,如果我们想生成一个工业级的软件说明文档该如何呢?这么多注释不能白写了呀。这时候我们就可以使用Sphinx来帮助我们实现自动化的说明文档生成,详情可以看《Sphinx入门——快速生成Python文档》。

    3.5.3 打包项目所需依赖包

    当我们代码也准备好了,说明文档也准备好了,距离交付别人就只差一个依赖包了。我们的项目可能会依赖很多第三方的包,如果不给别人一个依赖清单,那么别人也没有办法非常容易的复现你的程序,因为总会报各种各样的错误。这时候,我们又需要另一个神器了pipreqs
    首先使用命令行执行pip install pipreqs
    然后进入项目的文件夹里,执行下面的命令:

    pipreqs ./  # 报错就执行下面这条
    pipreqs ./ --encoding=utf-8
    

    这样就会生成一个requirement.txt文件,里面就是我们的依赖包了,等到再复现的时候,只需要执行pip install -r requirement.txt即可重装这些依赖了。

    4 小结

    至此,我们基本上讲述了如何实现教科书级的红警开源代码需要注意的事项,为以后我们更好的编码打下了基础。在将来,我们将会磨砺自己的编程技巧,终有一天做出一流的艺术品,为整个虚拟世界真真正正的贡献自己的一份力量!

    展开全文
  • 本文档旨在明确项目开发过程中go代码注释规范,并提供基于goland的注释模板设置指导。便于开发人员快速配置环境,高效、合规开展工作。 注释规范 总体原则 注释使用单个英文半角空格作为分隔符,避免注释中空格...

    文档目标

    良好的注释对项目后续的开发维护工作十分必要。本文档旨在明确项目开发过程中go代码的注释规范,并提供基于goland的注释模板设置指导。便于开发人员快速配置环境,高效、合规开展工作。

    注释规范

    总体原则

    1. 注释使用单个英文半角空格作为分隔符,避免注释中空格数量及格式混乱。
    2. 全部使用单行注释,禁止使用多行注释,// 后紧跟一个英文半角空格

    文件注释

    每个文件都要有一个注释,位于 package 之前,格式如下

    // @Author eric 2021/10/22 16:23:00
    package test
    

    结构体及接口注释

    每个自定义的结构体或者接口都应该有注释说明,对结构进行简要介绍,放在结构体定义的前一行,格式为: 结构体名, 结构体说明。同时结构体内的每个成员变量都要有说明,该说明放在成员变量的后面(注意对齐),示例如下:

    // User 用户对象,定义了用户的基础信息
    type User struct{
        Username  string // 用户名
        Email     string // 邮箱
    }
    

    函数及方法注释

    每个函数,或者方法(结构体或者接口下的函数称为方法)都应该有注释说明。内容包括:创建人、创建时间、功能描述、修改人、修改时间、修改原因。其中修改时间、修改人、修改原因只有在方法逻辑有大调整时增加。其他小的语法改动等不需要增加。如果修改是为了修复某个bug,需要在修改原因中写明bug编号。每个函数,或者方法(结构体或者接口下的函数称为方法)都应该有注释说明。内容包括:创建人、创建时间、功能描述、修改人、修改时间、修改原因。其中修改时间、修改人、修改原因只有在方法逻辑有大调整时增加。其他小的语法改动等不需要增加。如果修改是为了修复某个bug,需要在修改原因中写明bug编号。

    方法注释:
    // @Title hello
    // @Description 实现XXX功能
    // @Author eirc 2021-10-22 17:14:47 
    // @Param name
    // @Return string
    func(User) hello(name string) string{
    
    
    方法修改注释:
    // @Modified By eric 2021/10/22 17:20:00
    // @Modify description  修复bug0001
    

    方法内容超过30行的,或者有复杂/不易理解逻辑的,要在方法内按照逻辑增加注释说明。格式如下:

    // 未成年情况执行如下逻辑
    if   userAge < 18 {
    ……
    }
    

    import规范

    // 单行引入
    import  "fmt"
    // 多包引入,每包独占一行
    // 使用绝对路径,避免相对路径如 ../encoding/json
    import (
         "strings"
         "fmt"
    )
    

    注释模板配置

    这里基于goLand开发工具进行配置,goLand工具本身提供了快捷注释的方式,但是不能够满足所有需求。goanno是一款goland注释插件,这里推荐二者结合使用。注释模板配置方式如下。

    goLand文件注释模板配置

    1. goland 菜单路径: File->Settings->Editor->File and Code Templates 打开如下对话框

    在这里插入图片描述

    如上图所示,点击“+“ 创建名为”head“的include条目,内容如下(由于goland中time只返回时分,后边追加:00 保证时间格式统一为时分秒):

    // @Author zhangxinmin ${DATE} ${TIME}:00 
    package ${GO_PACKAGE_NAME} 
    
    1. 点击Files,选择Go File 配置内容如下

    在这里插入图片描述

    1. 配置完成 点击 Apply OK 按钮。新建一个go文件自动追加了作者及创建时间
      在这里插入图片描述

    goLand方法修改注释模板配置

    1. goland 菜单路径: File->Settings->Editor->File and Code Templates 打开如下对话框。
      点”+”选择Live Template,新建方法修改注释模板,配置内容如下
    // @Modified By eric $date$ $time$:00 
    // @Modify description $desc$ 
    

    在这里插入图片描述
    mmr 为自定义快捷键,可按照自己习惯定义。

    1. 点击 Edit variables 绑定变量值如下
      在这里插入图片描述
      date方法可以传入参数指定日期格式 如下:date(“Y-MM-dd H:mm:ss”) 2021-10-01 14:07:50

    配置完成 依次点击OK Define Apply OK 按钮,Define 按钮对话框中选择Go

    在这里插入图片描述

    1. 在代码中方法上 输入mmr 回车即可自动显示注释模板。如下图

    在这里插入图片描述

    Goanno方法、接口、结构体注释模板配置

    1. 安装Goanno插件,如下
      在这里插入图片描述

    2. 配置插件注释格式,Tools-> Goanno Settings
      在这里插入图片描述

    3. 配置内容如下,注意不要有多余行,每行后带空格

    Normal Method 配置内容:
    // @Title ${function_name} 
    // @Description ${todo} 
    // @Author zhangxinmin ${date} ${time} 
    // @Param ${params} 
    // @Return ${return_types} 
    
    interface配置内容
    // ${interface_name} 
    
    Interface Method 配置内容
    // @Title ${function_name} 
    // @Description ${todo} 
    // @Author zhangxinmin ${date} ${time} 
    // @Param ${params} 
    // @Return ${return_types} 
    
    Struct配置内容
    // ${struct_name} 
    
    Struct Field  不做配置
    

    配置完成点击submit

    1. 验证注释 在方法、结构体、接口上 使用快捷键 ctrl +alt +/ mac系统使用control + commond + / 快捷键, 可自动生成注释 如下截图
      在这里插入图片描述
    展开全文
  • 11个程序员幽默代码注释
  • C/C++代码注释自动删除工具(源代码)

    热门讨论 2011-11-30 12:31:11
    C/C++代码注释自动删除工具,工程编译之后生成的exe文件,文件执行之后会自动扫描文件所在目录以及子目录中的所有c、cpp、h、inl文件中的注释,并处理注释删除之后造成的空格或者空行,并将原始文件备份成tmp文件。...
  • 教你写好代码注释

    千次阅读 2019-12-08 21:35:31
    这时候,代码注释就可以发挥它的作用了——提高晦涩难懂的代码的可读性;注释可以起到隐藏代码复杂细节的作用,比如接口注释可以帮助开发者在没有阅读代码的情况下快速了解该接口的功能和用法;如果写的好,注释还...

    前言

    相信大家都会遇到这种情况:一周前自己写的代码,现在再拿出来看,发现读不懂了,“ 这代码是我写的???”。这时候,代码注释就可以发挥它的作用了——提高晦涩难懂的代码的可读性;注释可以起到隐藏代码复杂细节的作用,比如接口注释可以帮助开发者在没有阅读代码的情况下快速了解该接口的功能和用法;如果写的好,注释还可以改善系统的设计

    既然注释这么多好处,为什么我们程序员还是不愿意写注释?

    “代码都写不完了,哪有时间写注释,以后再补吧“

    时间不够论。这是最常见的原因,在交付速度飞快的今天,“代码写不完”是一个再常见不过的情况了,但写注释真的会导致需求延迟吗?绝不!相对于写一个接口的实现,写接口注释的时间可能只需要花费前者的5%。但不写注释,后面使用接口的人必须要多花费**50%**的时间去读懂代码!而且对于大部分程序员而言,“以后再补“大概要到2910年才能落实。

    “好的代码就是最好的注释,我的代码可读性很好,没必要写注释”

    好代码胜过注释论。不少程序员认为,好的代码就是最好的注释,只要代码可读性好,注释就可以省去。然而一个软件系统很多信息是无法通过代码呈现出来的,比如系统的设计思路、函数执行的预置条件等等。此外,代码可读性也不是绝对的,对于一个没有使用过Java 8 的 Lambda表达式的开发者而言,通篇的箭头“->“简直就是一场噩梦。

    ”过期的注释容易误导人“

    过期注释论。不可否认,过期的注释很容易误导读者,但是这并不能成为否认注释的借口。除非是重大的重构或重写,对注释进行大改动的情况很少出现。通常,在更改代码之后,只需花费极少的时间去更新注释,就可以避免过期注释这种情况了。

    注释的分类

    注释大致可以分成四类:接口注释、数据成员注释、实现注释和模块依赖注释。

    接口注释

    平时我们所说的接口,通常指的是一个类(包括interface、class、enum)和方法。对类而言,接口注释主要描述该类提供的功能;对方法而言,除了描述方法功能之外,方法的入参和返回值都要进行说明。当然,使用类/方法的一些预置条件和副作用等信息都需要在接口注释中提到。

    典型的接口注释(选自JDK 1.8中的String类)

    数据成员注释

    数据成员注释和接口注释在大多数情况下都是必须的,这对于让读者快速读懂代码有很大的帮助。数据成员包括类的普通成员变量和静态成员变量,数据成员注释除了描述数据成员的本身用途之外,成员的默认值、副作用等信息都需要提及。

    典型的数据成员注释(选自JDK 1.8中的String类)

    实现注释

    对于一段代码,如果无法一眼就看出其含义而需要深入分析其实现才能读懂,就需要添加实现注释对这段代码的含义进行说明。代码的实现注释通常不是必须的,如果一段代码每一行都需要注释,那就要重新审视一下这段代码的设计是否有合理了。此外,实现注释描述还需要描述一些代码无法体现,但是对于读者了解这段代码很有帮助的信息,比如代码的设计思路等。

    典型的实现注释(选自JDK 1.8中的String类)

    模块依赖注释

    模块依赖注释相对少见一些,主要描述两个相互依赖的模块的一些依赖信息,因为它并不属于单独某个模块,所以在哪里写这个注释需要认真衡量一下。实在找不到好的位置时,可以写一个类似README的文件,专门用于描述模块之间的依赖关系。

    典型的模块依赖注释(选自《A Philosophy of Software Design》中的例子)

    如何写好代码注释

    利用好注释模板

    注释模板为注释写作提供了极大的便利,我们常用的开发工具如IDEA、VS Code都对注释模板有很好的支持。在配置好注释模板之后(一般情况下默认模板即可),只需简单的操作,就能生成模板,我们只需往模板里填上内容即可。对于方法的接口注释,注释模板尤为方便,方法的入参和返回值标识注释模板都已经提供好。

    IntelliJ IDEA默认的注释模板

    不要重复代码

    注释与代码重复是开发者最容易犯的一个错误,这也是很多开发者认为注释是冗余的原因。确实,对于那些通过读代码可以很容易就推断出来的信息,注释就是多余的,更甚者,出现过期注释还容易误导读者。

    典型的重复代码的注释(选自《A Philosophy of Software Design》中的例子)

    某些程序员喜欢在注释中使用代码中的变量名或其中的单词,这种情况也是注释重复代码的一种体现。像下面的这个例子,注释完全就是冗余的,可以猜测开发者纯粹是为了注释而注释。

    使用代码变量名的注释

    注释也要分层

    在进行系统设计时,我们常常会采用分层架构,每一层负责不同功能。系统的顶层往往会更抽象一点,为功能调用者隐藏了很多细节(high-level);底层往往会更细节一点,实现系统的具体功能(low-level)。在进行注释写作时,我们也要学会对注释进行分层。high-level的注释要提供比代码更抽象的信息,比如代码的设计思路;low-level的注释要提供比代码更细节的信息,比如表示一个范围的两个参数是左闭右开还是左闭右闭;我们需要避免写出与代码同一level的注释,因为这往往就是上一节所提到的注释重复代码

    low-level注释写作指南

    对于需要通过阅读这一段代码才能获取的信息,就适合以low-level注释写在这段代码前面,一些常见的例子有:

    • 变量的单位是什么?
    • 表示范围的一组参数是左闭右开还是左闭右闭?
    • 某个变量为null时代表什么含义?
    • 某个资源应该由谁来负责释放,接口调用者还是接口提供者?

    low-level注释不能太过抽象,否则就失去了其应有的作用。

    太过抽象的low-level(选自《A Philosophy of Software Design》中的例子)

    典型的low-level注释(选自《A Philosophy of Software Design》中的例子)

    high-level注释写作指南

    high-level注释的作用是隐藏具体实现细节,快速让读者对整一段代码有一个全局的了解。high-level注释除了描述对代码进行抽象的概括(What)之外,还经常描述代码的设计思路(Why),这有助于帮助读者更容易、深入地了解整个系统。high-level注释不应该描述具体代码实现的信息,更不能犯注释重复代码的错误。在写high-level注释之前,先问一下自己:

    • 这段代码要做什么事情?
    • 这段代码最核心的功能是什么?
    • 怎样才能以最简单的描述表达这段代码的核心功能?

    太过细节的high-level注释(选自《A Philosophy of Software Design》中的例子)

    典型的high-level注释(选自《A Philosophy of Software Design》中的例子)

    规范接口注释

    接口注释是用的最多的一种注释,它可以让读者快速了解整个模块的功能并知道如何使用该接口,而不必花费大量时间去阅读源码。

    对于一个的接口注释,其通常是high-level的注释,主要描述这个类提供的一些功能;

    对于一个方法的接口注释,则同时需要包括high-level和low-level的注释,常见的有以下几点:

    • 整个方法提供的主要功能
    • 方法的所有参数和返回值含义
    • 调用该方法的副作用(比如改变了系统的某个状态)
    • 该方法可能抛出的所有异常
    • 调用该方法的预置条件(比如调用该方法前,系统必须处于某个状态)

    实现注释描述what、why,而不是how

    写实现注释时需要记住的最重要的一点就是,描述代码是做什么的(what)和为什么这么做(why),而不是描述怎么做(how)。因为实现代码本身就是how,如果还添加描述how的注释,那就犯了“注释重复代码”的错误了。

    典型的描写how的实现注释(选自《A Philosophy of Software Design》中的例子)

    典型的描写what的实现注释(选自《A Philosophy of Software Design》中的例子)

    实现注释通常不是必须的,对于一些简短的、功能单一的函数,一个好的函数命名即可替代实现注释。

    总结

    注释是软件开发过程中的性价比极高的一个工具,它只需要花费20%的时间,即可获取80%的价值。代码注释最重要的作用就是让读者可以在不读源码的情况下,快速了解一段代码的主要功能。注释的作用还远远不止这些,John Ousterhout在《A Philosophy of Software Design》一书中提到,写注释最好的时机是在写代码之前。这样,注释就相当于一种设计工具:在编码前通过注释描述这段代码的功能,然后在通过编码实现这个功能,如果这个过程有偏差,则再调整注释。写注释时要切记两点,不要重复代码更新代码后也要更新注释!前者可以减少冗余的注释,后者则可以避免因为过期的注释而误导读者。

    当然,注释也不是越多越好,如果一个系统写的注释太多,很有可能就是该系统设计得过于复杂,只能通过注释来帮助读者理解整个系统。

    总而言之,学会怎么写好代码注释,是一个程序员的必备技能,这即是为了开发团队的其他成员,也是为了未来的自己。

    展开全文
  • 代码注释去除工具

    热门讨论 2012-02-13 18:05:34
    本工具可以快速清除源代码中的各类注释文本,目前支持的格式有SQL脚本文件、C/C++/C#文件、VB/VBScript文件
  • 代码注释删除小工具(java)

    热门讨论 2010-04-24 18:15:07
    用java编写的代码注释删除小工具,能去文本中掉//和/* */注释。 第一个按钮的功能为去掉文本框1中代码的注释,输出到文本框2. 第二个按钮的功能为批量删除文件中的注释,并输出到当前目录(新文件名为xxx.txt)。但...
  • Java代码注释规范

    千次阅读 2019-03-23 15:29:51
    代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。下面说一下我们在日常开发中使用的代码注释规范,供...

     

    代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。下面说一下我们在日常开发中使用的代码注释规范,供大家参考下。

    1. 注释形式统一

    在整个应用程序中,使用具有一致的标点和结构的样式来构造注释。如果在其它项目中发现它们的注释规范与这份文档不同,按照这份规范写代码,不要试图在既成的规范系统中引入新的规范。

     

    1. 注释内容准确简洁

    内容要简单、明了、含义准确,防止注释的多义性,错误的注释不但无益反而有害。

    注释条件

    1、基本注释

    (a)    类(接口)的注释

    (b)    构造函数的注释

    (c)     方法的注释

    (d)    全局变量的注释

    (e)    字段/属性的注释

     

     备注:简单的代码做简单注释,注释内容不大于10个字即可,另外,持久化对象或VO对象的gettersetter方法不需加注释。具体的注释格式请参考下面举例。

    2、特殊必加注释

    (a)    典型算法必须有注释。

    (b)    在代码不明晰处必须有注释。

    (c)     在代码修改处加上修改标识的注释。

    (d)    在循环和逻辑分支组成的代码中加注释。

    (e)    为他人提供的接口必须加详细注释。

     

     备注:此类注释格式暂无举例。具体的注释格式自行定义,要求注释内容准确简洁。

    注释格式

    1、单行(single-line)注释:“//……”

    2、块(block)注释:“/*……*/”

    3、文档注释:“/**……*/”

    4、javadoc 注释标签语法

    @author   对类的说明 标明开发该类模块的作者

    @version   对类的说明 标明该类模块的版本

    @see     对类、属性、方法的说明 参考转向,也就是相关主题

    @param    对方法的说明 对方法中某参数的说明

    @return   对方法的说明 对方法返回值的说明

    @exception  对方法的说明 对方法可能抛出的异常进行说明

    参考举例

    1. 类(接口)注释

    例如:

    /**

    * 类的描述

    * @author Administrator

    * @Time 2016-11-14:49:01

    *

    */

    public classTest extends Button {

      ……

    }

     

     

    2.   构造方法注释

    例如:

    public class Test extends Button {

      /**

       * 构造方法 的描述

       * @param name

       *       按钮的上显示的文字

       */

      public Test(String name){

         ……

      }

    }

     

     

    3.   方法注释

    例如

    public class Test extends Button {

      /**

       * 为按钮添加颜色

       *@param color

             按钮的颜色

    *@return

    *@exception  (方法有异常的话加)

    * @author Administrator

    * @Time2012-11-20 15:02:29

       */

      public voidaddColor(String color){

         ……

      }

    }

     

     

    4.   全局变量注释

    例如:

    public final class String

       implements Java.io.Serializable, Comparable<String>,CharSequence

    {

       /** The value is used for characterstorage. */

       private final char value[];

       /** The offset is the first index of thestorage that is used. */

       private final int offset;

       /** The count is the number of charactersin the String. */

       private final int count;

       /** Cache the hash code for the string */

    private int hash; // Default to 0

    ……

    }

     

     

    5.   字段/属性注释

    例如:

    public class EmailBody implements Serializable{

       private String id;

       private String senderName;//发送人姓名

       private String title;//不能超过120个中文字符

       private String content;//邮件正文

       private String attach;//附件,如果有的话

       private String totalCount;//总发送人数

       private String successCount;//成功发送的人数

       private Integer isDelete;//0不删除 1删除

       private Date createTime;//目前不支持定时 所以创建后即刻发送

       privateSet<EmailList> EmailList;

    ……

    }

     

    其实规范是自己订的,只要团队中大家都统一遵守,统一规范,就会取得好的效果,希望对平时不加注释的朋友有点帮助。

     

     

    展开全文
  • 代码注释检测工具,用于进行代码注释统计,非常不错的哦。
  • 代码注释

    千次阅读 热门讨论 2018-04-01 01:24:25
    只要写代码,就会遇到代码注释的问题。在不同的公司,不同的项目组,不同的项目中,可能会有不同的注释标准。有些标准让我们感觉很受益,有些则让我们感觉很反感。而对于没有明确标准的项目,我们往往会遇到...
  • idea常用插件及代码注释

    千次阅读 2020-07-06 22:31:33
    阿里巴巴代码规范检查插件 https://plugins.jetbrains.com/plugin/10046-alibaba-java-coding-guidelines Key promoter 快捷键提示插件 https://p...
  • 程序员的代码注释需要写么?

    千次阅读 2021-11-01 15:13:15
    “别给糟糕的代码注释——重新写吧。”—Brian W. Kernighan与P. J. Plaugher 什么也比不上放置良好的注释来得有用。什么也不会比乱七八糟的注释更有本事搞乱一个模块。什么也不会比陈旧、提供错误信息的注释更有...
  • C语言代码注释规范

    千次阅读 2019-03-19 09:08:42
    不是代码bug,我要讲注释风格。这位看官,既然来了,且读且评吧。故事是真实的,如有雷同纯属巧合。 事情是这样的,有人离职,公司调我补缺。那个系统一直有个工程师在维护,参与该系统的新人来了又走,他始终泰若...
  • github上看各路大牛大神的项目代码,经常会看到各种神注释......那么问题就来了:大神是如何在代码里搞的这些图片代码呢?打死我也不信是大牛大神一个一个打上...
  • 超经典的java代码注释格式化模版及配置说明。
  • DBN代码注释

    2014-11-02 18:17:55
    deep learning 代码的代码注释

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 1,449,852
精华内容 579,940
关键字:

代码注释

友情链接: Snake.zip