精华内容
下载资源
问答
  • 这几天,红警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 小结

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

    展开全文
  • java代码注释规范引(阿里巴巴开发规范-注释规约)结合注释规约,在IDEA下设置相应的注释模板1,安装阿里巴巴开发规约的IDEA提示插件,这样能够在很大程度上规范自己的编程规范,在出现代码编写风格不规范的情况下会...

    引(阿里巴巴开发规范-注释规约)

    1. 【强制】类、类属性、类方法的注释必须使用 Javadoc 规范,使用/*内容/格式,不得使用
      // xxx 方式。
      说明:在 IDE 编辑窗口中,Javadoc 方式会提示相关注释,生成 Javadoc 可以正确输出相应注
      释;在 IDE 中,工程调用方法时,不进入方法即可悬浮提示方法、参数、返回值的意义,提高
      阅读效率。
    2. 【强制】所有的抽象方法(包括接口中的方法)必须要用 Javadoc 注释、除了返回值、参数、
      异常说明外,还必须指出该方法做什么事情,实现什么功能。
      说明:对子类的实现要求,或者调用注意事项,请一并说明。
    3. 【强制】所有的类都必须添加创建者和创建日期。
    4. 【强制】方法内部单行注释,在被注释语句上方另起一行,使用//注释。方法内部多行注释
      使用/* */注释,注意与代码对齐。
    5. 【强制】所有的枚举类型字段必须要有注释,说明每个数据项的用途。
    6. 【推荐】与其“半吊子”英文来注释,不如用中文注释把问题说清楚。专有名词与关键字保持
      英文原文即可。
      反例:“TCP 连接超时”解释成“传输控制协议连接超时”,理解反而费脑筋。
    7. 【推荐】代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑
      等的修改。
      说明:代码与注释更新不同步,就像路网与导航软件更新不同步一样,如果导航软件严重滞后,
      就失去了导航的意义。
    8. 【参考】谨慎注释掉代码。在上方详细说明,而不是简单地注释掉。如果无用,则删除。
      说明:代码被注释掉有两种可能性:1)后续会恢复此段代码逻辑。2)永久不用。前者如果没
      有备注信息,难以知晓注释动机。后者建议直接删掉(代码仓库保存了历史代码)。
    9. 【参考】对于注释的要求:第一、能够准确反应设计思想和代码逻辑;第二、能够描述业务含
      义,使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同
      天书,注释是给自己看的,即使隔很长时间,也能清晰理解当时的思路;注释也是给继任者看
      的,使其能够快速接替自己的工作。
    10. 【参考】好的命名、代码结构是自解释的,注释力求精简准确、表达到位。避免出现注释的
      一个极端:过多过滥的注释,代码的逻辑一旦修改,修改注释是相当大的负担。
      反例:
      // put elephant into fridge
      put(elephant, fridge);
      方法名 put,加上两个有意义的变量名 elephant 和 fridge,已经说明了这是在干什么,语
      义清晰的代码不需要额外的注释。
    11. 【参考】特殊注释标记,请注明标记人与标记时间。注意及时处理这些标记,通过标记扫描,
      经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
      1) 待办事宜(TODO):( 标记人,标记时间,[预计处理时间])
      表示需要实现,但目前还未实现的功能。这实际上是一个 Javadoc 的标签,目前的 Javadoc
      还没有实现,但已经被广泛使用。只能应用于类,接口和方法(因为它是一个 Javadoc 标签)。
      2) 错误,不能工作(FIXME):(标记人,标记时间,[预计处理时间])
      在注释中用 FIXME 标记某代码是错误的,而且不能工作,需要及时纠正的情况。

    结合注释规约,在IDEA下设置相应的注释模板

    1,安装阿里巴巴开发规约的IDEA提示插件,这样能够在很大程度上规范自己的编程规范,在出现代码编写风格不规范的情况下会给出相应的提示及建议:

    在这里插入图片描述

    2,安装JavaDoc在IntelljIDEA下的插件,可以单个或批量生成代码注释:

    插件安装:
    在这里插入图片描述
    安装完成后再IDEA中即可通过快捷键:Alt+Insert 生成代码javadoc的注释:
    在这里插入图片描述
    缺点是:由该插件生成的代码注释风格无法进行修改,所以在类的注释上也就无法添加author及create time的标志性字段,这与《阿里巴巴开发规约》的第3条相违背,但是在看dubbo或者其它阿里系产品的时候,发现他们自己开发的代码中类的注释也是采用的类似javadoc的插件自动生成的注释,类上面也没有加类似的标志性字段,自己也没有遵守相应的规范?
    在这里插入图片描述

    3,利用Live Template手动添加注释模版

    还记得在idea中使用sout,编辑器会自动提示是否为System.out.println();的功能,这里就是类似这样的实现。
    在Live templates中点击右侧的+号,选择第二项TemplateGroup,创建一个模板分组,而后在该分组下同样点击右侧的+号,这次选择第一项LiveTemplate。
    在这里插入图片描述
    这个名称尽量选择短一点,这其实就涉及到一个快捷键的问题,当输入cc的时候,就会自动生成类的注释,注释模板就采用阿里建议的模板风格:

    	/**
    	 *TODO:
    	 *
    	 *@author xxxx
    	 *@date $date$
    	 */
    

    在这里插入图片描述
    当编写完类需要完成什么功能后需要将TODO字样去掉,合乎《规范》第11.1的规定。

    综述:对于类注释采用liveTemplate配置注释模板,对于方法及字段注释采用javadoc插件自动生成的注释字样已完全够用,满足相应的需求。

    在这里插入图片描述

    附:IDEA生成javadoc的操作:

    在Tool中直接点击generate javaDoc,然后选择需要生成的项目及生成位置即可:
    在这里插入图片描述

    展开全文
  • 代码注释

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

            只要写代码,就会遇到代码注释的问题。在不同的公司,不同的项目组,不同的项目中,可能会有不同的注释标准。有些标准让我们感觉很受益,有些则让我们感觉很反感。而对于没有明确标准的项目,我们往往会遇到“百花齐放,百家争鸣”般的注释。我无法给出一个明确的标准,只是在此探讨下:什么样的注释不应该写,什么地方需要写注释。(转载请指明出于breaksoftware的csdn博客)

    “不”的原则

    不是每行代码都需要写注释

            这个原则源于之前我和同事的一个争论。当时我们讨论代码注释该怎么写的问题,最终同事抛出这么一个观点:“我之前在X为干过,那儿就需要每行代码都写注释,所以我们应该执行这样的标准”。想必大家都可以猜到那是一家什么公司,但是从我个人角度分析,同事之前可能去的是一家假的“X为”公司。因为我觉得那个公司不应该如此没有技术品味吧?

            之后的探讨,我们将以画作为例。因为画是一种艺术表达,而我们的代码也应该写的和艺术品一样,表达出一种美。下图是梵高的《向日葵》原作,图中只有若干向日葵花、花瓶、地面(或者说是承载体)等元素。

            假如我们对这份“代码”每行加一个注释,则呈现如下

            各位看官感觉如何?我觉得如果梵高画的如果不像向日葵的话,这样搞点“注释”可能还有存在的意义。但是如果作品足够表意,那么再加上注释就是画蛇添足。这种为写注释而写注释是非常不可取的。为什么呢?因为

     

    • 增加编码人员无价值的工作量
    • 让编码人员降低对自己代码质量的要求,因为“反正要写注释”,叫index还是叫xpoesiejd无所谓。
    • 让对自己编码有艺术美感的编码人员产生抵触。比如我们要是让梵高给他原作加上上图一样的注释,我想梵高可能早就不想活了。

            但是我相信我同事可能说的是“真”的,但是这个“真”被我打了一个引号。因为我怀疑他之前可能在一家给X为干活的外包公司工作。也许X为的确有严格的代码注释量要求(也许“注释行数”/“代码行数”>0.5),于是这家外包公司就做了一个“任何一行代码都要写注释”的要求。我想如果他们真的这么去执行了,代码的注释量的确是上去了,但是或许注释的质量降低了,或者工作效率降低了。

    不要写废话

            上图是欧仁·德拉克罗瓦的著名油画《自由引导人民》。这幅作品是为了法国七月革命而作,最前方的那个女性是克拉拉·莱辛,象征着自由女神。她左手边男孩象征着阿莱尔,右手边戴大礼帽的男性象征着资产阶级,贝雷帽男性则象征着工人。可以见得这幅画包含了大量的背景知识。但是如果我们用废话注释它就是

            是不是要抓狂?对于这样显而易见的信息写注释就是“废话”!

    不要写错误的注释

            上图是徐悲鸿的著名油画《田横五百士》。我们抛开这幅画的时代意义,单从历史画角度来看,大师给我们传达了一个错误的信息——人物的着装不符合故事地域年代(秦末齐国地区)。如果该幅画没有留下名字,后人通过画作的衣着信息(可以看成是一种注释)对该画所表达的故事进行推理时,可能出现断代错误,从而得出的故事和作者想表达的不同。

    不要乱留名

            

            这幅是元代赵孟頫的《水村图卷》。请注意一下右上角那个大大的、红红的、方方正正的印章——乾隆御笔之宝。可能你会觉得乾隆爷给这幅画加盖了自己的印章,会导致该幅画价值大大增加,但是实际效果是恰恰相反。乾隆爷是有名的毁画大师,他经常在一些有名的作品上胡乱加盖自己的印章——留名。于是这些画作经他这么一折腾就会贬值。连乾隆爷的名字都那么不值钱,我们何必要在代码中乱留名呢?

            但是如果这份文件是你编写的,你还是要在版权信息中写入你的名字。这就和中国古人画作一般都会自己签名和盖自己印章一样。

            可能你会辩解,说:我添加的这段逻辑非常重要,我要留名以便以后有人能找到我。我觉得这个问题应该这么看:如果你的代码重要程度可以颠覆原作,我觉得你可以考虑重写一份并署上自己名字;如果没那么重要还是把留名交给原作者吧,毕竟你的成果是在他基础之上获得呢。

    不要注释掉代码

            我想这个问题是最最常见的。大家翻翻自己项目的代码,可能都会遇到这种现象。当我们不需要一段代码时,可能也会估计是“永远不用了”还是“暂时不用了”。于是很多人对“暂时不用了”的代码使用注释方式使其无效。但是一般来说,这种“暂时不用了”的代码很有可能就是“永远不用了”,而人们已经忘记要去删除它了。这个现象在实际项目中比比皆是。所以个人觉得:不要的代码要果断删除。即使以后真的要用了,我们可以使用代码管理工具(svn或者git)方便的找回。

            下图是库尔贝的油画《受伤的男人》。其实作者在呈现这幅画之前,画布上画了一个女性头部。可能作者觉得这块逻辑可能没用了,于是就用黑色把“她”抹去,从而也成就了这幅名画。假想作者如果使用“注释”的手段将这颗头颅保留在画作中,将是如何吓人的一幅场景。

    不要写小故事

            在工作中,可能某个类的设计思路来源于和产品经理或者技术经理的思想碰撞,可能这个过程很精彩,有些编码者就将整个故事用注释的方式放在代码中。也有可能这个类和历史上一个著名人物有关,比如我们要编写斐波拉契数列实现,就将斐波拉契平生故事放到代码里。我觉得这些内容放在代码中是非常不合适的,也许你觉得很精彩,但是别人很有可能不关心啊。

            比如下图是米开朗琪罗的《耶稣受难》

            现在我们觉得耶稣受难前“最后的晚餐”故事很精彩,于是我们把这段《新约圣经》“注释”到画作中

            米开朗琪罗如果这么作画,可能现在我对他的认知中少了“画家”这一项。

    不要有宗教倾向

            这个问题在国内不算太大的问题。因为程序员大部分是无神论者。当我们看到“佛祖保佑”或者“God save me”是往往是莞尔一笑。但是我们不能假设以后阅读这份代码的人没有宗教信仰,也许他信奉的和你正好相反呢。代码是没有宗教的,编码者是有的。

            我们比较常见是的“佛祖保佑 永无bug”

            个人比较反感这种做法。所以我会在自己的项目中,将这种注释都删掉。假如我们的代码要依靠神来保佑,我只能质疑你代码的质量是不是已经超神了。我们还是要信奉二进制的。

    不要博人一笑

            代码是严谨的逻辑表达,不要写一些逗人开心的内容。可能上例中“佛祖保佑,永无bug”在一些编码者看来只是为了博人一笑。但是我觉得阅读代码是一件需要连续动脑筋的事,如果我们阅读过程被这些“笑话”不停打断,那么最终的理解效率得有多低?

            比如著名的《清明上河图》,它包含了大量的社会信息。假如我每隔一段注释一个笑脸,那么这幅画可能就没那么高的艺术价值了。

    不要批判前人

            写出完美的代码的确是非常稀少的。所以我们阅读别人代码时,往往可以发现很多问题。在感觉不爽时,可能心中默默鄙视一下作者;再不爽时,可能和同事数落一下作者;再再不爽时,可能就要在代码中批判一下作者。但是这种注释对代码是有意义的么?而且并不是我们总是对的。由于对问题的理解深度、角度不同,编码者就是可能会写出让你不满意但是符合他自己原则的代码。

            比如梵高的《星空》

            像我这种鉴赏能力比较差的,的确很难说出他画的哪儿好了。假如我给这幅画做了如下注释

            我想我并不会获得别人的赞许,可能全是对我的鄙视。那怎么办?我觉得我应该去画一幅符合我心目中“星空”的油画,这样供其他人在我和梵高中做个选择。或许这是一种自不量力,但是这却是一种对原作者的尊重。

    “要”的原则

            说了这么多“不”的原则,其实我知道我还是没有说全。但是我们换个角度,如果我们知道“要”的原则,然后对其取反,就是涵盖所有“不”的原则了。

            在讨论这个话题之前,我先说下我对代码和注释的认识。

            首先我认为代码要写的和注释一样表意。也就是说我们要穷尽自己的思想,努力掌控每个名词、每个动词、每个换行、每个空格、每个组织形式以达到让代码可以自说明逻辑及业务。

            其次代码和注释应该是一个整体。往往一份文件包含代码和注释两部分,而阅读这份文件也有两个主体——编译器和人。编译器只是通过代码来获得逻辑信息,而人的要通过代码和注释一起理解逻辑和业务。

            基于第二点,我认为一份文件最好只有一个故事线——只需要用代码去表达,因为它是人和编译器同时可以去理解的。如果一个故事经过两个人去讲述,随着时间推移,最终会变成两个故事。这是非常可怕的。

            所以我的观点是:如果代码足够表意,且不违背常理,不应该去添加注释。反之则需要加注释。

            但是现实社会中,有时候很难做到不违背常理。因为我们这个世界随机性太强,有时候我们就要放弃一些我们认识的“常理”去达到期望的目的。这个时候我们代码的表达能力可能就是不足的了,就需要注释来表达。

            比如齐白石的画作中,寿桃往往是用来祝寿的

            这个常理我们中国人都可以理解。但是假如我们看到下面这幅画,你觉得他是齐白石用来干嘛的?

            它其实也是用于祝寿的。它是齐白石向蒋公祝60大寿时送的,和这幅画一起送的还有一副对联——人生长寿,天下太平。完整的版本是

            假如觉得这副对联还不够表达“潜台词”,则上联左上侧“主席寿”几个字则可以完全说明了吧。

            这幅《松柏高立图》在2011年以4.255亿被拍卖,而它则是我认为需要写“注释”的一个典型代表。

    展开全文
  • 前端代码注释模板

    万次阅读 2020-06-04 10:18:20
    前端代码注释 /** * @name 名字 * @abstract 申明变量/类/方法 * @access 指明这个变量、类、函数/方法的存取权限 * @author 函数作者的名字和邮箱地址 * @category 组织packages * @copyright 指明版权信息 * @...

    前端代码注释模板,请根据自己的使用情况自行筛选使用。

    /**
    * @name 名字
    * @abstract 申明变量/类/方法
    * @access 指明这个变量、类、函数/方法的存取权限
    * @author 函数作者的名字和邮箱地址
    * @category 组织packages
    * @copyright 指明版权信息
    * @const 指明常量
    * @deprecate 指明不推荐或者是废弃的信息
    * @example 示例
    * @exclude 指明当前的注释将不进行分析,不出现在文挡中
    * @final 指明这是一个最终的类、方法、属性,禁止派生、修改。
    * @global 指明在此函数中引用的全局变量
    * @include 指明包含的文件的信息
    * @link 定义在线连接
    * @module 定义归属的模块信息
    * @modulegroup 定义归属的模块组
    * @package 定义归属的包的信息
    * @param 定义函数或者方法的参数信息
    * @params 定义函数或者方法的参数集合信息
    * @return 定义函数或者方法的返回信息
    * @see 定义需要参考的函数、变量,并加入相应的超级连接。
    * @since 指明该api函数或者方法是从哪个版本开始引入的
    * @static 指明变量、类、函数是静态的。
    * @throws 指明此函数可能抛出的错误异常,极其发生的情况
    * @todo 指明应该改进或没有实现的地方
    * @var 定义说明变量/属性。
    * @version 定义版本信息
    * @createdTime 创建时间
    * @lastModifiedTime 最后更改时间
    */
    

    欢迎朋友们评论区留言拓展~

    展开全文
  • 代码注释规范

    千次阅读 2016-06-23 17:40:14
    代码注释规范
  • java eclipse 注释代码快捷键 取消代码注释快捷键

    万次阅读 多人点赞 2016-10-08 10:02:20
    注释掉代码: 把要注释的代码选中,按Ctrl+Shift+/ /* */ 形式的 ctrl+/ //形式的 取消代码注释: 把要注释的代码选中,按Ctrl+Shift+\ /* */ 形式的 ctrl+/ //形式的
  • 前端代码注释

    千次阅读 2019-03-04 03:58:42
    代码注释为啥很重要呢?以下是我的一些想法: 提高代码可读性 《黑客与画家》里面有句话“程序写出来是给人看的,附带能在机器上运行”。既然是给人看的,我觉得有两个方面就比较重要。一、代码写的好,好的代码...
  • 注释掉代码: 把要注释的代码选中,按Ctrl+Shift+/ /* */ 形式的 ctrl+/ //形式的 取消代码注释: 把要注释的代码选中,按Ctrl+Shift+\ /* */ 形式的 ctrl+/ //形式的
  • 30 多个有内味道且笑死的人代码注释

    万次阅读 多人点赞 2020-08-26 08:01:40
    代码注释,有些人说它太丑,也有些人说它是标准和良好的做法。在本文中, 列出了一些在编程中遇到的有趣的代码注释。 注释 1 // Weed Effect ! 这是杂草效应的意思?不是很懂,有谁知道,可以留言一下.
  • Java代码注释规范

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

    千次阅读 2014-10-21 20:46:59
    注释掉代码: 把要注释的代码选中,按Ctrl+Shift+/ /* */ 形式的 ctrl+/ //形式的 取消代码注释: 把要注释的代码选中,按Ctrl+Shift+\ /* */ 形式的 ctrl+/ //形式的
  • vscode代码注释与取消注释快捷键: ctrl+/
  • JavaScript代码注释范例

    千次阅读 2018-06-10 21:23:43
    #JavaScript代码注释范例&gt; 做为一个有情怀的Coder,最近收集了一下JavaScript代码注释范例,希望能够帮助大家撸得一手妖媚而又放荡的Bug。## 普通注释### 单行注释**使用 ```//``` 作为单行注释。****单行...
  • VUE代码注释规范,代码规范

    千次阅读 2019-08-15 10:52:09
    VUE代码注释规范,代码规范 背景 其实关于这一点我是深恶痛绝呀,你说我们吧eslint开了,来敲代码,就能把你的代码给规范了吧,关于组件命名和src结构都是按照VUE目录给的(项目成员已构造),功能注释和调试代码...
  • IDEA开发工具删除代码注释

    千次阅读 2019-07-24 23:50:10
    IDEA开发工具删除代码注释删除注释 删除注释 有人的地方就会有需求,有时候我们希望删除我们自己代码中的所有的注释,不管这是基于任何原因的总是有这方面的需求,那么基于我们的IDEA开发工具我们该如何删除我们的...
  • JAVA代码注释规范

    千次阅读 2017-04-25 01:59:27
    代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。下面说一下在开发中使用的代码注释规范,供大家参考下...
  • JDK1.7-HashMap源代码注释

    千次阅读 多人点赞 2020-07-05 09:19:19
    JDK1.7-HashMap源代码注释
  • Javascript 代码注释规范

    千次阅读 2017-05-10 12:17:07
    javascript 代码注释规范 注释一般来说是好事情,但新手编程经常犯错误。他们写注释解释“代码是什么”,但这样解释性注释应该越少越好。 严肃地说,好的代码应该容易理解无需注释。有个极好规则:如果代码不清楚...
  • intellij自动生成java代码注释,包括java文件头部的注释,java方法的注释
  • python整行代码注释掉 取消代码注释

    千次阅读 2020-06-01 10:50:04
    1.选中要操作的代码区域 2.按下Ctel+/
  • VSCode 中添加代码注释

    千次阅读 2020-07-20 10:57:34
    首先打开VSCode,按快捷键 Ctrl+shift+p ;输入snippets 点击回车,选择新建代码片段,点击... "zhushi": { "prefix": "ldj", "body": [ "/*", "* 代码注释", "* 说明:", "* 模块:", "* 作者:李德军", ...
  • java代码注释规范

    万次阅读 多人点赞 2012-11-20 20:20:13
    代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。下面说一下我们在诉求网二期开发中使用的代码注释规范...
  • antlr提取代码注释

    千次阅读 2016-05-19 09:38:51
    使用antlr提取源代码注释的时候,需要定义不同的channel来导流,将注释导流到特定channel
  • vs 修改代码注释快捷键

    千次阅读 2018-01-29 18:18:33
    visual Studio 英文版修改代码注释快捷键
  • Eclipse代码注释和取消注释快捷键

    千次阅读 2015-05-22 09:42:47
    许久不编程,快捷键都忘记了,方便记忆! 代码注释快捷键:ctrl+shift+/ 取消注释快捷键:ctrl+shift+\
  • 教你写好代码注释

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

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 163,385
精华内容 65,354
关键字:

代码注释