精华内容
下载资源
问答
  • 避免在代码里写注释

    千次阅读 多人点赞 2013-03-14 14:21:45
    如果用很多注释来“装饰”代码是件好事的话,那么在代码中加入大片大片的注释便是锦上添花了。是这样吗?事实上不完全是这样的。过犹不及,好心也会办坏事。 '************************************************* ' ...

    如果用很多注释来“装饰”代码是件好事的话,那么在代码中加入大片大片的注释便是锦上添花了。是这样吗?事实上不完全是这样的。过犹不及,好心也会办坏事。

    '*************************************************
    ' Name: CopyString
    '
    ' Purpose: This routine copies a string from the source
    ' string (source) to the target string (target).
    '
    ' Algorithm: It gets the length of "source" and then copies each
    ' character, one at a time, into "target". It uses
    ' the loop index as an array index into both "source"
    ' and "target" and increments the loop/array index
    ' after each character is copied.
    '
    ' Inputs: input The string to be copied
    '
    ' Outputs: output The string to receive the copy of "input"
    '
    ' Interface Assumptions: None
    '
    ' Modification History: None
    '
    ' Author: Dwight K. Coder
    ' Date Created: 10/1/04
    ' Phone: (555) 222-2255
    ' SSN: 111-22-3333
    ' Eye Color: Green
    ' Maiden Name: None
    ' Blood Type: AB-
    ' Mother's Maiden Name: None
    ' Favorite Car: Pontiac Aztek
    ' Personalized License Plate: "Tek-ie"
    '*************************************************

    我常常不看开发者写的注释。似乎他们并不明白,其实他们的代码已经告诉了我它是怎样工作的;我们需要注释告诉我们的是,程序为什么这样工作。代码注释已被广泛地误解和滥用,以致于你都开始怀疑它们原本的价值——注释还有存在的必要吗?你在期望什么呢?要当心!这里有一段完全没有任何注释的代码:

    r = n / 2;
    while ( abs( r - (n/r) ) > t ) {
      r = 0.5 * ( r + (n/r) );
    }
    System.out.println( "r = " + r );

    明白这段代码想要做什么吗?它看起来一清二楚,但到底是干什么用的呢?

    让我们加上一行注释:

     // 用“牛顿-拉夫逊”近似法求解n的平方根
    r = n / 2;
    while ( abs( r - (n/r) ) > t ) {
      r = 0.5 * ( r + (n/r) );
    }
    System.out.println( "r = " + r );

    这个应该就是我想要的了。不是吗?它介于完全没有任何注释与每隔一行就规规矩矩写上史诗般的注释这两种极端之间,看似一个不错的折中——你满意了吗?

    未必!与其添加注释,我更愿意把这段代码重构成这样:

    private double SquareRootApproximation(n) {
      r = n / 2;
      while ( abs( r - (n/r) ) > t ) {
        r = 0.5 * ( r + (n/r) );
      }
      return r;
    }
    System.out.println( "r = " + SquareRootApproximation(r) );


    我一行注释也没有加,但这段神秘的代码现在已经非常容易理解了。 

    尽管注释本身说不上好或者坏,它们却常常被用作支撑代码的“拐杖”。你应该总是专注于编写代码,而忘了还有注释这种东西的存在。这会迫使你竭尽全力使用最简单、最直白、最能自我说明的方式把代码写出来。

    为了让你的程序员同伴们更易于阅读和理解你的代码,如果你已经重写、重构、甚至重新设计了很多遍——当你已经一筹莫展,已经想不出任何办法可以让你的代码变得更加浅显易懂——这时候,也只有在这时候,你才应该迫不得已地加上些注释来解释你的代码是做什么的。

    就像Steve Yegge指出的那样,这是初级开发者与高级开发者之间的一个关键差别:

    坦率地说,要是在以前,让我一下子看太多的代码会让我崩溃,它的复杂度已经超越了我能接受的极限。而当我不得不在那些代码的基础上继续工作的时候,我通常会把它们重写,或者至少也会写上大量的注释。现如今,当我碰到这种情况的时候我会披荆斩棘快速通过,而不会(过多地)抱怨。当我在脑子里有了一个明确的目标、并且有一段复杂的代码要写时,我会把时间花在代码实现上面,而不是(用注释)写下它的故事、讲给我自己听。

    初级开发者依靠注释来讲故事,而实际上他们应该依靠代码本身。注释是“旁白”,它们有其自身的价值,但绝不能用来替代(故事里的)情节、人物和场景。

    或许这才是关于代码注释不可告人的小秘密:想要写出好的注释,你必须是一位优秀的作家。注释跟代码不一样,它不是给编译器看的。注释是用来和其他人类交流想法的文字。尽管我跟(大多数)程序员同伴们关系很好,但我必须承认,与其他人有效沟通真的不是我们的强项。我曾经收到过我们小组里的一位程序员发来的电子邮件,里面只有三段,但着实把我搞得晕头转向。我们能相信这样的人会在代码里写出清晰、易懂的注释吗?于是我想,或许我们中的一些人去做那些我们擅长的事情会更好些——那就是,为编译器写代码,并且尽可能写得清楚些,而只把注释当作是最后没有办法的办法。

    写出好的、有意义的注释是很难的。就像写代码一样,它是一门艺术;或许还要更加艺术一点!就像Sammy Larbi在“Common Excuses Used To Comment Code and What To Do About Them”(注释代码的常见借口以及应对方法)一文中所说的那样,如果你觉得你的代码在没有注释的情况下显得过于复杂、很难被人理解,那只能说明你的代码写得很糟糕。重写你的代码吧,直到它不再需要任何注释。如果经过了这些努力,你仍然觉得注释是必需的,那么就尽你所能加上注释吧。切记,小心!

    展开全文
  • 一、写代码写注释写代码写注释”自从学编程,这就话就伴随着你。可见注释的重要性。 注释的作用: 说明函数的功能 说明函数参数的意思 说明函数这样设计的原理(计算公式) 说明函数的使用场景 作者和日期 ...

    一、写代码要写注释

    “写代码要写注释”自从学编程,这就话就伴随着你。可见注释的重要性。
    注释的作用:

    • 说明函数的功能
    • 说明函数参数的意思
    • 说明函数这样设计的原理(计算公式)
    • 说明函数的使用场景
    • 作者和日期
    • 说明变量的作用
    • 函数调用方法与注意事项

    总之为了能让读这个函数的人明白这个函数的功能,可以注释各种各样的信息。而没有这些注释文字,就不太容易看懂函数的功能与调用用方法。没有注释的情况下,隔一段时间之后,自己也看懂的自己所写函数的功能了。因此,很多书籍、老师、领导、同事、包括你自己,都会告诉你“一定要写注释,不写是万万不能的”。

    二、注释标准格式

    其实注释没有特别严格的注释格式,但是为了使得注释整齐简洁。还是会有一些格式的要求的。针对不同开发平台,不同编程语言,都有各自不同的注释推荐格式。(高级一些IDE会提供注释快捷键)下面分别列举一些常见的注释格式:

    1. C#
    /// <summary>
    /// 这个方法的作用就是求两个整数之间的最大值
    /// </summary>
    /// <param name="n1">第一个整数</param>
    /// <param name="n2">第二个整数</param>
    /// <returns>返回比较大的那个数字</returns>
    public static int GetMax(int n1, int n2) {}
    
    1. Qt_C++
    /*
     * @Brief:  
     * @Param:  First
     * @Param:  Second
     * @Return: NULL
     */
     void DataManager::SaveValue(int First, int Second) {}
    
    1. Java
    /**
    * This method inputs a number from the user.
    * @return The value output as a double.
    * @exception IOException On input error.
    */
    public double getNumber() throws IOException {}
    
    1. 单片机中的C语言(格式1)
    /*
    ******************************************************************************************
    *	函 数 名: TMC26X_ReadWriteByte
    *	功能说明: TMC26X读写一个字节函数
    *	形    参: val写入值
    *	返 回 值: 读回状态值
    ******************************************************************************************
    */
    UINT8 TMC26X_ReadWriteByte(UINT8 val)
    
    
    
    1. 单片机中的C语言(格式2)
    /**
     * @brief	开始输出指定频率的PWM波
     * @param	frequency PWM频率 单位:Hz
     * @retval	无
     */
    void BSP_PwmStart(uint32_t frequency) {}
    

    三、注释类型有哪些?

    其实一般没有这个概念,只是本文为了更好的解释说明注释的作用,给分别进行了定义。分别如下:

    • 翻译类型注释
    • 函数编写背景说明注释
    • 实现原理注释
    • 编程技术注释

    下面编写一个真实的函数来举例说明各种类型的注释:

    //此函数用于建立“温度”与“温度传感器电阻”之间的线性关系   //编写背景说明注释
    //函数:计算直线公式                             //翻译类型注释
    //功能:通过2个点来计算出直线方程的k和b              //原理类型注释
    //参数:w1 第一个温度值, 
    //参数:z1 第一温度值对应的温度传感器电阻值           //翻译类型注释,把字母翻译成有实际意义的名字
    //参数:w2 第二个温度值, 
    //参数:z2 第二温度值对应的温度传感器电阻值           
    //参数:k 计算出来的斜率                         //翻译类型注释,把一个字母翻译成实际对应的意义
    //参数:b 计算出来的截距          
    //返回值:无                                  //编程技术注释
    void JiSuanZhiXianGongShi( float w1, float z1, 
                            float w2, float z2,
                            float* k, float* b) {
        float temp_k; //临时变量
        float temp_b;
    
        //使用到饿直线公式为:y = k*x + b             //原理类型注释
        //以下代码通过“代入法”分别计算出k和b
        temp_k = (z2 - z1) /(w2 - w1);
        temp_b =  z2 - temp_k * w2;
    
        //通过指针类型形参返回计算结果                //编程技术注释
        *k = temp_k;
        *b = temp_b;
    }
    
    
    
    

    从以上代码注释实例中可以看到,“原理注释”和“背景说明注释”相对来说很重要,如果不写的话,阅读代码的人就看不懂代码。而其余的主要是“翻译类注释”,即把一个字符符号翻译转化为有实际意义的名字(解释其代表的意义)。

    四、“其实不用写注释”(^_^哈哈哈)

    以上说明文字和例子,充分举例说明了“代码注释”的重要性。但是也许你也发现这样一个现象。在实际编码工作中,大部分人是不写注释的。他们为什么不写。是偷懒吗?

    1. 嗯,是有偷懒的嫌疑,那么能给出偷懒的理由吗?理由如下:
    • 我写的是应用软件代码,有几万行代码等着我写,如果不是重要的注释,我是不写的。因为给每个函数都配一个汉语注释是不现实的。
    • 软件开发中,大部分注释是“翻译类型注释”,我只要把函数名字和变量名字起合适了,是不需要再去写啰嗦的注释(我要避免过度注释)
    • 切换中文输入法很麻烦,我英语比较好,同事也能看懂。因此我直接用“英语”写函数名字和变量名字即可。不需要写中文注释。
    • 写注释之后还要维护注释,否则注释反而造成了错误的引导,所以我干脆不写。
    • Linus Torvalds(Linux内核之父)给出的回复是:“Read the fu*king source code”。
    1. 嗯,以上的理由也挺充分。那么不写注释的代码是什么样子的,别人能看懂吗,请看如下代码。
    • 使用英语函数名字和变量名字代替“注释”(注意:仅保留原理类型注释)
    void Get_K_B_OfLinearFunction( float temperature1, float resistance1, 
                                float temperature2, float resistance2,
                                float* k, float* b) {
        float temp_k;
        float temp_b;
    
        //y = k*x + b 
        temp_k = (resistance2 - resistance1) /(temperature2 - temperature1);
        temp_b =  resistance2 - temp_k * temperature2;
    
        *k = temp_k;
        *b = temp_b;
    }
    
    
    • 使用合适的“拼音”变量名字代替“注释”(注意:仅保留原理类型注释)
    void HuoQuZhiXianFangChengDe_K_B( float wendu1, float dianzu1, 
                                float Wendu2, float dianzu2,
                                float* k, float* b) {
        float temp_k;
        float temp_b;
    
        //y = k*x + b 
        temp_k = (dianzu2 - dianzu1) /(wendu2 - wendu1);
        temp_b =  dianzu2 - temp_k * wendu1;
    
        *k = temp_k;
        *b = temp_b;
    }
    
    1. 要不要写注释的结论
      很显然,这两个函数例子中几乎没有写注释,仅注释了一个“直线方程的公式”。也就是说我们几乎没有“注释可看”,而我们可以看到的是“函数名字”和“参数变量名字”,然后再阅读函数中的代码实现。阅读代码的人可以准确的知道这个函数的真正功能。在理解的同时,还会对代码有一种“切实”的理解。因此调用这个函数的时候可以做到“心知肚明”。

      而如果只看注释不看代码,在调用函数的时候,就会有个“镜中花,水中月”的一种虚幻的感觉。因此还是的阅读一下函数实现代码。

      因此,最终的结论是:
      在良好“函数名字”和“变量名字”的辅助下(前提下),是不需要写“注释的”。如果要写,只要写“实现原理类型”和“设计背景说明类型”的注释即可。(另外可以专门去阅读一下大型开源软件的源码,看看大牛们是否写注释)。

    五、必须需要写完整注释的特例

    1. 接口函数
      另外要说明一点,在写接口函数的情况下,注释是要求“完完整整”写全的。比如常见的大公司提供的SDK。其中sdk内部实现功能的代码是不必写注释的。但是对外提供的“接口”函数,是必须要完整写注释的(包括函数功能,参数说明,使用方法说明,返回参数说明)。
    2. 硬件驱动函数(单片机程序代码函数)
      由于单片机的代码函数都和硬件紧密相关。函数中经常操作的的是“寄存器”,寄存器一般都是字母缩写。如果不写注释的话,那是真的无法看懂。其次,单片机的代码量相对应用软件来说代码很少,因此给每个函数都配一个中文注释是可接受的。因此要求“单片机”的程序代码都要写注释。
    展开全文
  • 代码注释怎么

    千次阅读 2017-05-15 00:20:33
    注释怎么写注释的作用是什么?我认为注释最终作用无非就两个。 1.和伪代码一样的作用,为接下来要实现的功能出一个指导性的算法思路。只是没有伪代码详细。但是也指出了完成此功能的大体算法思路。 2.给看代码...

    注释怎么写

    注释的作用是什么?

    我认为注释最终作用无非就两个。

    1.和伪代码一样的作用,为接下来要实现的功能写出一个指导性的算法思路。只是没有伪代码详细。但是也指出了完成此功能的大体算法思路。

    2.给看代码的人一个解释性说明。注意看代码的人包括你自己。让看你代码的人可以快速的浏览你的代 码,而不至于每看一行都要一层
    一层的方法看下去,才能了解你这个方法到底在干什么。

    简单的说注释作用就是:写的时候提供算法思路。读的时候能快速了解你大约是怎么完成这个功能。

    注释越多越好?

    很多公司或者个人希望开发者注释写的足够详细。以为这样就可以提高可读性。我觉得这个想法是有问题的。

    1.首先开发者写注释的时间可能超过了写代码。如果把大把的时间浪费在写注释上了,那么开发者还怎么能设计出足够好的代码呢。

    2.看注释的人不得不一边看注释,一边看代码。我觉得没有哪个程序员会在看了足够详细的注释的时候就真的相信了注释而不看
    具体的代码了。或者看完代码之后不看下注释确认下自己的理解对不对。那么就会造成老师期末考试的时候划重点的时候说每章
    的都 是重点。

    注释应该怎么写?

    下面是我个人对注释写法的一些见解。

    1.其实很简陋啊。就是你实现的时候的伪代码的超级精简版。你要完成一个功能你就是 1.先xxx 2.在xxx 3.在xxx。那就把这个 1,2,3 注释写
    上去就好了。如果有其他很重要的步骤的话,也可以写下注释说明。但是主流程 1,2,3必须要清楚。

    举个例子:
    一个人早上上班的流程。
    起床->刷牙->吃早饭->坐公交->刷卡->早会->coding。

        /**
         * 去上班  起床->刷牙->吃早饭->坐公交->刷卡->早会->coding。
         *
         * @param test
         */
        public void goWork( String test ){
            //起床
            wakeUp();
            //刷牙
            toothbrushing();
            //吃早饭
            haveBreakfast();
            //坐公交
            takeBus();
            //刷卡
            swipingCard();
            //早会
            takeMorningMeeting();
            //coding
            coding();
        }

    看上面的注释部分,相信你会非常快的了解这个人去工作需要哪些步骤。具体的起床穿什么衣服,刷牙用什么牙膏等更细节的问题,本身就不是这个
    goWork() 方法应该考虑的了。你想了解你去看具体的代码块就好了。
    如果在坐公交的时候出现 bug。那么开发者是不需要慢慢的找坐公交在哪开始的了。你可以直接的找到 takeBus() 开始仔细查找就好了。

    2.该暴露的你必须要暴露出来让其他开发者来看到。别人可以一目了然的知道你这个功能时候怎么实现的。
    函数不是越短越好,是越简单越好。是算法上的清楚或者说是逻辑上的简单

    下面是我 review 代码经常会遇到的问题。
    例如我们把 坐公交,刷卡 这两个方法写到 吃早饭方法里。

      /**
         * 去上班  起床->刷牙->吃早饭->坐公交->刷卡->早会->coding。
         *
         * @param test
         */
        public void goWork( String test ){
            //起床
            wakeUp();
            //刷牙
            toothbrushing();
            //吃早饭
            haveBreakfast();
            //早会
            takeMorningMeeting();
            //coding
            coding();
        }
    
        //吃早饭
         private void haveBreakfast() {
            //先吃早饭
    
            //坐公交
            takeBus();
            //刷卡
            swipingCard();
        }

    代码,变短了。从计算机的角度讲没毛病。吃完饭了坐公交然后刷卡。但是程序员只是了解计算机并不是真的是计算机。从 goWork() 函数上很直观看的话,我就以为是起床->刷牙->吃早饭->早会->coding。然后坐公交出现了 bug 那么恭喜你慢慢找吧。

    上面那个例子同时违背了方法的责任单一原则。即一个方法只能抽象一件功能。
    去上班可以是一个功能,起床可以是一个功能,但是吃早饭,坐公交,刷卡肯定不是一个功能。

    实践中的经验。

    1.一个步骤下面还有子步骤。

    不是说注释下面就是对应一个方法。很多时候因为其他的原则,比如说没有复用性的是没有必要写成方法的。这种时候一个功能会是很多子功能的集合。那么我建议子功能的注释最好和上级功能的注释区分开。以表明这只是一个子流程。

    例子:
    主流程使用 ===开头
    子流程使用 ——————-开头。
    样式明确表示了功能级别。长度起到了看起来方便(因为,像伪代码的缩进)。

    public final String apLogin(final HttpServletRequest request, HttpServletResponse response) {
            //===本次请求的原数据写日志==================
            String parameters = JSON.toJSONString(request.getParameterMap());
            //-------------获取 token 做为本次请求的日志 id-
            String logId = StringUtil.getToken();
            //-------------本次请求的数据写日志------------
            logger.debug("{}订制终端获取页面参数为:{}", logId, parameters);
    
            //===解析参数==============================
            String deviceId = request.getParameter("dev_id");
            String userMac = StringUtil.formatMac(request.getParameter("client_mac"));
            String gwAddress = request.getParameter("gw_address");
            String gwPort = request.getParameter("gw_port");
            String url = request.getParameter("url");
            String publicUserIp = request.getHeader(Constants.X_FORWARDED_FOR);
            String publicUserPort = request.getHeader(Constants.X_FORWARDED_PORT);
    
            //===校验参数==============================
            ApPortalServiceDTO apPortalServiceDTO =
                    new ApPortalServiceDTO(deviceId, userMac, gwAddress, gwPort, url, publicUserIp, publicUserPort);
            String validateResult = validateLoginParameters(apPortalServiceDTO);
            if ( null != validateResult) {
                logger.error("{}订制终端获取页面服务参数校验不通过:{},参数为:{}",
                    logId, validateResult, JSON.toJSONString(apPortalServiceDTO));
                return JSON.toJSONString(ResultDTO.getParameterErrorResultDTO(validateResult));
            }
    
            //===去数据中心查询 portal 页信息===============
            //-----------写日志需要的信息---------------
            GlobalDTO globalDTO = new GlobalDTO(
                logId, FunctionNameConstants.AP_PORTAL, GlobalDTO.assembleLogValue(deviceId, userMac));
            //-----------查询页面信息------------------
            ResultDTO resultDTO = apPortalService.getApPortal(globalDTO, apPortalServiceDTO);
            if (ResultDTO.isResultError(resultDTO.getResultCode())) {
                return JSON.toJSONString(resultDTO);
            }
    
            try {
                //===重定向拉去拉取相应的页面====================
                response.sendRedirect((String) resultDTO.getData());
                logger.info("{}apLogin重定向到{}完成", logId, resultDTO.getData());
                //===返回客户端结果
                return JSON.toJSONString(new ResultDTO());
            } catch (Exception e) {
                logger.error("{}重定向到:{}发生异常:",
                      JSON.toJSONString(globalDTO), resultDTO.getMessage(), StringUtil.getExceptionStackTrace(e));
                return JSON.toJSONString(ResultDTO.SEND_REDIRECT_EXCEPTION);
            }
        }
    展开全文
  • 优秀的程序员真的不写注释吗?

    万次阅读 多人点赞 2020-05-11 07:02:23
    我在很多地方看到这样一个观点,“请停止写注释,因为只有烂的代码才需要注释。”这个观点非常巧妙,它让我想起了孟子的一句话,“杨氏为我,是无君也;墨氏兼爱,是无父也。无父无君,是禽兽也。” 动不动就骂别人...

    我在很多地方看到这样一个观点,“请停止写注释,因为只有烂的代码才需要注释。”这个观点非常巧妙,它让我想起了孟子的一句话,“杨氏为我,是无君也;墨氏兼爱,是无父也。无父无君,是禽兽也。”

    动不动就骂别人是“禽兽”,我总觉得有点不妥,这很不符合孟子的浩然之气啊。有些大牛也有孟子这样的觉悟,如果有人要他给自己的代码加上注释,就好像是对他的一种侮辱:“我的代码写得这么优雅,你难道看不懂吗?注释是多余的!”

    我必须得承认,每个程序员都应该有一颗追求“优雅”的心,力争自己的代码更易阅读和理解——不只是针对机器,还有我们程序员同行。但不是每个程序员在一开始都能写出“高标准”的代码的,就好像不是所有君王和百姓都能搞清楚孟子的治国齐家理念的。

    在我刚回洛阳的那段时间,过得非常痛苦。因为我刚接手了别人留下的一个项目,关于大宗期货交易的。后端代码是用 Java 写的,但有很多 bug 在里面,动不动就资金结算失败,甚至内存溢出,要解决这些问题,只有一个办法,就是彻底搞懂这些代码。

    否则,根本无从下手。这就好像,你和朋友开车出去自驾游,去很远很远的地方,朋友开累了,需要休息,这时候,如果你没考过驾照,那就抓瞎了,只能把车停路边,等朋友的疲劳消退了,才能继续上路。

    我就抓瞎了。凭良心说,前同事留下的代码是精彩绝伦的,如果换做是我来写,真不一定能写得出来。毕竟大宗期货交易本身还是有点难度的,需要竞价撮合,这个业务理解起来比股票还要复杂些。

    股票涨了就赚,跌了就亏。期货不同的,买涨能赚,买跌也能赚。不过业务上的复杂还是次要的,重要的是代码里的注释非常稀有,就好像詹姆斯高斯林头上的发丝一样稀有。

    况且,国内程序员的英语功底你懂的,变量、方法、类、接口、枚举的命名无法做到真正意义上的名如其意。再加上,有些方法的行数多达三四百行,从头看到尾,看得只想捶自己。

    没办法,我的解决办法就是,看懂一行就加一行注释,毕竟注释总比代码要容易理解啊。就好像,我们在调用一个不熟悉的 API 时,只要代码的文档说清楚它是干嘛的,我们就可以用,就敢用,至于实现的细节,暂时没有理解也没关系。

    差不多花了两个月的时间(非常漫长、非常煎熬)吧,我总算是把项目中核心的代码给研究清楚了。搞清楚之后,那些之前怎么改都改不掉的 bug 也就迎刃而解了。

    这也就是为什么,我倡导大家去读源码的一部分原因了,除了学习,读源码是解决 bug 的杀手锏。要读懂源码,注释是必不可少的。不信,你看看 Java 的源码,每个变量、每个方法、每个类,注释都非常详细,详细到你替源码的作者感到心累。

    在我看来,Java 源码的作者绝对是这个世界上最优秀的程序员,连他们都写注释,那些声称“请停止写注释”的号召者是不是要啪啪啪地打脸,直到打肿为止。

    不要怀疑自己,写注释并不会证明你的代码就是烂代码。我相信,你应该买过电子产品,比如说鼠标、键盘、耳机、手机等等,所有的产品包装里除了产品本身,使用说明书是必不可少的。我就问一句,“手机没有使用说明书,咱这些后浪还能不会用?”

    写注释不是我们的错,软件本来就是复杂的。尤其是我们这些英语不是主力语言的人来说,注释显得尤为重要。我可能属于记忆力不好的那一种,隔个十天半个月,再去回头看那些我自己敲的代码,有时候真有点见着陌生人的感觉:“这代码是我写的吗?怎么有点面生啊?”

    大部分人写的代码都要升级重构,对吧?不论是语言本身版本的升级,还是我们自身能力的成长。假如在升级重构的时候,没有这些注释的帮助,真有点爬泰山的感觉,累啊,亲。

    再者说,大牛也不敢保证自己的代码是没有问题的,对吧?但注释是不会骗人的,它的意义是明确的。你可能会忘记代码是干嘛的,但我敢保证,注释能够唤醒你的记忆。

    写出好的、有意义的注释其实是有难度的,就像写代码一样。在追求卓越的路上,代码和注释其实是相辅相成的。注释会让你的代码更易阅读,代码会让你的注释更富有逻辑。

    即便是你的代码已经优雅到不需要注释,那只是在你的层面上。对于你的同事,你代码后来的负责者,就不一定了。所见略同的英雄并不会很多,你以为很优雅的代码没准在别人眼里就是一坨垃圾,而你的注释很可能会帮助别人“恍然大悟”,明白代码的意义。乖乖地写注释吧,对你对别人都有好处。

    另外,我想说一句,注释就好像是代码的一个蓝图,也或者是对代码的一个总结。在你写代码之前,脑子里肯定要想清楚你要实现什么,怎么实现,把这些作为注释写下来绝对可以帮助你写出更优雅的代码。在代码写完之后,通过注释进行总结,还能对代码进行一些升华,没准还能在总结的过程中想到更好的代码方案。

    我还见到有大牛信誓旦旦地说,写注释就好像是给不会游泳的人扔一个救生圈,他永远也学不会游泳。咋眼一看,这句话说得很有道理,对吧?在大牛们看来,要让一个新人快速成长,最好的办法就是把没有注释的代码扔给他看。

    纯属扯淡,恐怕这个新人没入门就放弃了吧?我已经三十一岁了,不,我已经十八岁了,还不会游泳呢?别听那些大牛们的鬼话,我就不信,他自己没写过注释。

    总之一点,注释并不会妨碍你写出优雅简洁的代码,它只是程序固有的一部分而已

    如果觉得文章对你有点帮助,请微信搜索「 沉默王二 」第一时间阅读。本文已收录 GitHub,传送门~ ,里面更有大厂面试完整考点,欢迎 Star。

    我是沉默王二,一枚有颜值却靠才华苟且的程序员。关注即可提升学习效率,别忘了三连啊,点赞、收藏、留言,我不挑,嘻嘻

    展开全文
  • 编写代码时,注释写还是不写

    千次阅读 2014-11-24 12:39:47
    作者 & 编辑:按键学院 【按键精灵】 小编听过一句很有意思的话: ...“好的代码本身就是最好的注释一堆注释本身就说明代码有问题。” 其实众说纷纭,各有道理。每件事都有它的正反两面,优胜劣势。 在此
  • 代码注释应该怎么

    千次阅读 2016-02-28 20:28:19
    前两天有同事向我抱怨不会写代码注释,不知道些什么,明明很简单的功能啊,一看就懂了,还怎么注释?
  • 教你代码注释

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

    千次阅读 2012-11-21 20:27:47
     了这么多年了代码了,见过很多人还是规规矩矩的将代码写好,而且并一个高质量的注释来让代码更加饱满;也见过很多人起来代码行云流水,潇潇洒洒,但是一句注释也没有;所以我就经常看到这样的现象和听到这样...
  • Pycharm批量注释代码和取消注释代码

    万次阅读 2018-12-27 15:25:31
    注释代码和取消注释代码的快捷键都一样 ctrl + /
  • 记得在学校的时候,老师教育我们,写代码一定要注释,并且很多时候都强调我们注释的重要性,和不建议使用goto语句那个道理一样,铭记在心中。 到公司以后,终于看到了实战中的项目是个什么样子,领导让我svn...
  • Java代码注释

    千次阅读 2015-05-27 17:21:38
    曾经我对“一份好的代码里注释至少要占到一半的份量”这样话深信不疑,我也不厌其烦的给每一个函数都加上javadoc,对此,我深感自豪;而对于别人写代码不加注释的“坏习惯”,我深表遗憾。然而当我读完Robert的...
  • 如何写注释

    千次阅读 2018-09-20 09:32:36
    如果能从代码本身看出的事实写注释。 这样注释完全多余,从代码本身就可以看出代码的意思。 也不能使用跟代码一样的意思重复注释,比如: //Find a Node with the given 'name' or return NULL Node * ...
  • 程序员应该避免写注释

    千次阅读 多人点赞 2014-07-31 17:38:16
    我很赞成这两篇文章的观点《世上最糟糕的两个变量名》以及陆其明老师翻译的《避免在代码里写注释》,有一个好的变量名、方法名其实就是一段很好的注释了,并且还会“自动更新”,你不用在未来优化这段代码的时候同步...
  • 写代码注释的重要性

    千次阅读 2015-09-20 17:58:30
    大神说,他代码优秀到不用写注释。。。。我也不知道他有多优秀,我想看看其他比较知名的框架代码是怎么的,于是,我试着第一次npm install jquery,震惊了。。。。基本每行都有注释。。  不管大家说jquery...
  • VS2017 C++ 代码片段 多行注释与取消注释

    万次阅读 多人点赞 2018-10-03 15:20:40
    1、VS2017 代码片段 多行注释 (1)选中要 注释代码段; (2)按Ctrl + K 键; (3)再按Ctrl +C 键。 2、VS2017 代码片段 取消注释 (1)选中要 取消注释代码段; (2)按Ctrl + K 键; (3)再按Ctrl...
  • 代码规范-注释

    千次阅读 2016-08-07 18:19:27
    代码规范-注释引言-《代码大全》对于投机取巧的代码注释是错误的,注释不应该帮扶难度大的代码,就像kernighan和plauger强调的:”不要注释糟糕的代码—-应重写之。”很多人支持优质的代码应该是自解释的在程序员的...
  • 如何好的代码注释

    千次阅读 2011-12-23 16:22:10
    怎样好的代码注释  以下13个小技巧可以使得你的代码在长时间内依然能够保持容易理解和维护。 1. 对不同级别的代码进行注释 对于不同级别的代码块,要使用统一的方法来进行注释。例如: 对于每一个...
  • 代码注释

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

    千次阅读 2018-02-03 17:53:26
    结构清晰简单、很容易维护的代码可以少甚至不写注释多了注释反而会降低工作效率。 代码越复杂越不容易维护,维护的人越是参差不齐,越是需要认真写注释。 判断注释、文档的够不够其实很容易验证。如果代码...
  • 转自:新浪科技 ...新浪科技讯 19日晚间,技术论坛出现了一篇讨论阿里旗下虾米音乐Mac版客户端中关于VIP会员代码注释,上面的图片中出现了所谓的“穷逼VIP(活动送的那种)”。 相关代码页面
  • Python代码注释应该怎么

    千次阅读 2017-12-15 14:36:42
    https://zhuanlan.zhihu.com/p/22663276?refer=passer http://zh-google-styleguide.readthedocs.io/en/latest/google-python-styleguide/python_style_rules/
  • 对于类中的注释,我们可以通过IDEA自动生成。 如IDEA 可以通过:File->Settings->Editor->File and Code Templates->Includes->File Header来设置模板,这样新建文件时,IDEA会按照设置的模板,会...
  • 热爱spring源码的同学,应该都希望在自己的spring源码jar包里面注释来加深对源码的理解,这篇博客主要就是告诉大家如何做到这点: 1、下载spring源码 我这里是下载的最新版本的spring源码,并且使用的是马云...
  • Java代码注释规范

    千次阅读 2019-03-23 15:29:51
    代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为注释而注释。下面说一下我们在日常开发中使用的代码注释规范,供...
  • html怎么注释代码 HTML中的注释 (Comments in HTML) The comment tag is an element used to leave notes, mostly related to the project or the website. This tag is frequently used to explain something in ...
  • Javascript 代码注释规范

    千次阅读 2017-05-10 12:17:07
    javascript 代码注释规范 注释一般来说是好事情,但新手编程经常犯错误。他们注释解释“代码是什么”,但这样解释性注释应该越少越好。 严肃地说,好的代码应该容易理解无需注释。有个极好规则:如果代码不清楚...
  • 代码注释规范

    千次阅读 2016-06-23 17:40:14
    代码注释规范
  • c++代码文档化注释

    千次阅读 2018-10-10 14:42:29
    近段时间,一直在学习华为C语言编程规范...在使用过程中,我已经深深地喜欢Doxygen,并在写代码时使用Javadoc注释风格。  本文由三部分组成:1)工具下载及安装;2)编写Doxygen可识别的注释;3)利用Doxygen工具将...

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 1,315,949
精华内容 526,379
关键字:

代码里写注释怎么写