开发者社区> 问答> 正文

如何正确地给代码写注释?

4000积分,笔记本电脑包*5

每个开发者都会讨厌两件事情——阅读没有注释的代码和给代码写注释。虽然无注释的代码也许终不可得,但是审视我们的代码结构减少注释,那也是非常值得的。那么如何正确地给代码给注释呢?

本期话题
1、工作中你遇到过的糟糕注释或优秀注释有哪些?
2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗?

本期奖励:
截止2024年1月10日24时,参与本期话题讨论,将会选出5名幸运用户获得笔记本电脑包*1

幸运用户获奖规则:中奖楼层百分比为17%,32%、53%,76%、94%的有效留言用户可获得互动幸运奖。如:活动结束后,回复为100层,则获奖楼层为 100✖17%=17,依此类推,即第32、53、76、94位回答用户获奖。如遇非整数,则向后取整。如:回复楼层为84层,则84✖17%=14.28,则第15楼获奖。

未获得实物礼品的参与者将有机会获得 10-200 积分的奖励。

image.png

注:楼层需为有效回答(符合互动主题),灌水/复制回答将自动顺延至下一层。如有复制抄袭、不当言论等回答将不予发奖。阿里云开发者社区有权对回答进行删除。获奖名单将于活动结束后5个工作日内公布,奖品将于7个工作日内进行发放,节假日顺延。

展开
收起
提个问题 2023-12-25 14:53:49 1828 34
168 条讨论
参与讨论
取消 提交讨论
  • 1、工作中你遇到过的糟糕注释或优秀注释有哪些?
    遇到过完全没有注释、注释和代码毫无关系、离职的人给后人留下的大坑
    2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
    建立规范化的代码体系、构建一本账管理对相关代码建立索引机制

    2024-01-09 19:11:44
    赞同 24 展开评论 打赏
  • 1、工作中你遇到过的糟糕注释或优秀注释有哪些?

    完全不写注释。方法名 参数名随意

    注释与代码不一致,留下过时的注释导致误导。

    注释使用拼写错误、语法错误,或者没有遵循团队约定。

    2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗

    良好的命名和自解释的代码,使用正确的英文单词命名

    2024-01-09 10:54:50
    赞同 17 展开评论 打赏
  • 一万年太久,只争朝夕。

    注释的目的是为了解释代码的功能、实现思路、注意事项等,提升代码的可读性和可维护性。

    1.简单业务功能,如增删改查,简单注明即可,如:create、delete、edit、select。

    2.复杂业务功能,使用索引,链接到企业知识库或者网络文库、博客等。

    /**
      * <a href="https://aliyun.com">业务功能说明</a>
    */
    public List<DiscordAccount> list(){
      return this.loadBalancer.getAllInstances().stream().map(DiscordInstance::account).toList();
    }
    
    2024-01-09 07:31:35
    赞同 14 展开评论 打赏
  • 糟糕的注释:

    # 增加1到变量
    counter += 1
    
    // 如果x小于10,执行下面的代码
    if (x < 10) {
        // 做一些事情
        doSomething();
    }
    

    优秀的注释:

    # 该循环用于计算数组元素的总和
    total_sum = 0
    for num in numbers:
        total_sum += num
    
    // 验证用户是否已登录
    if (user.isAuthenticated()) {
        // 在数据库中保存用户信息
        saveUserData(user);
    } else {
        // 如果未登录,记录错误日志
        logError("User not authenticated");
    }
    

    减少注释的方法:

    1. 良好的命名和自解释的代码:

    # 糟糕的注释
    def calc(a, b):
        result = a + b  # 将a和b相加得到结果
        return result
    
    # 优秀的例子
    def add_numbers(num1, num2):
        return num1 + num2
    

    2. 模块化和函数化:

    # 糟糕的注释
    # 处理用户输入,验证并保存到数据库
    # ...
    # 验证邮箱格式是否正确
    # ...
    # 保存用户信息到数据库
    # ...
    
    # 优秀的注释
    def process_user_input(input_data):
        validate_and_save_to_database(input_data)
    
    def validate_and_save_to_database(data):
        validate_email_format(data['email'])
        save_user_data_to_database(data)
    
    def validate_email_format(email):
        # 验证邮箱格式的代码
    
    def save_user_data_to_database(user_data):
        # 保存用户信息到数据库的代码
    

    3. 自解释的代码结构:

    // 糟糕的例子
    function complexFunction(x, y, z) {
        // 一大堆复杂的代码
        // ...
    }
    
    // 优秀的代码
    function separateTasks(x, y, z) {
        performTask1(x);
        performTask2(y);
        performTask3(z);
    }
    
    function performTask1(parameter) {
        // 任务1的代码
    }
    
    function performTask2(parameter) {
        // 任务2的代码
    }
    
    function performTask3(parameter) {
        // 任务3的代码
    }
    
    2024-01-08 17:04:11
    赞同 17 展开评论 打赏
  • 1、工作中你遇到过的糟糕注释或优秀注释有哪些?

    糟糕的例子://注释“某年某月谁改的“
    OS 这名字都不知道是否还在这个碳基世界,目前的形态是碳基还是炭集,写的这个鬼注释仿若大圣五指山前留得那个记号,有个浮云用。
    优秀://存在原因+参数应用范围+举例

    2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗

    难办难办 经常看到一个代码写得一塌糊涂,注释乱七八糟,观者恨不得问候代码创造者,发现出自己手。
    不然就像word插入注释一般,又影增加冗余响速度。

    2024-01-08 14:30:52
    赞同 9 展开评论 打赏
  • 2有一些方法可以减少注释,但依然能让他人看懂代码:
    使用有意义的变量和函数命名:选择具有描述性的变量和函数名称,可以减少对注释的需求。通过命名清晰地表达代码的意图和功能。
    模块化和函数化:将代码分解为小的模块和函数,每个模块和函数只关注单一的功能,减少代码的复杂性和理解难度。
    编写自解释的代码:通过良好的代码结构、逻辑和设计模式,使代码本身尽可能地清晰地表达其意图和功能。
    添加文档注释:在函数和类的开头,使用适当的文档注释(如Javadoc或Python的docstring)来描述函数的输入、输出和功能。
    提供示例代码:在代码中添加一些示例用法,可以帮助其他开发者更好地理解代码的使用方式和预期行为。

    2024-01-08 13:46:19
    赞同 5 展开评论 打赏
  • 2减少注释但保证可读的方法,我会:
    注重代码结构和命名的可读性。

    使用自 explanatory 的函数/变量名字。

    注释重要的逻辑变化或 boundary case。

    注释公共库或复杂算法。

    加入必要的测试用例。

    保持简洁高效的代码风格。

    2024-01-08 13:46:18
    赞同 5 展开评论 打赏
  • 糟糕的注释可能包括以下几种情况:

    没有注释:完全没有注释,或者只有少量的注释,导致代码缺乏解释和文档,使得其他开发者难以理解代码的意图和功能。

    冗长而无用的注释:注释内容过多,但没有提供实质性的信息,只是重复了代码本身已经表达的内容。这样的注释会增加代码的冗余,降低可读性。

    错误的注释:注释与代码不一致,或者过时的注释导致误导。如果注释不反映实际的代码逻辑或者没有及时更新,那么将给其他开发者带来困惑和错误的理解。

    不规范的注释:注释使用拼写错误、语法错误,或者没有遵循团队约定和最佳实践。不规范的注释会给阅读者带来困惑,降低代码的可读性和专业性。

    过度注释:在每一行或每一个语句都添加详细注释,而这些注释对于理解代码并无实际帮助。过度注释会干扰代码的阅读,使得代码显得混乱。

    单行注释过长:单行注释过长,超过一定的长度限制,难以阅读。注释应该简洁明了,提供必要的信息,避免过度冗长。

    2024-01-08 13:47:13
    赞同 5 展开评论 打赏
  • 1有遇到过,很多时候都是忘记注释了,然后后期连自己都忘了是啥意思了

    2024-01-08 13:46:54
    赞同 5 展开评论 打赏
  • 1 优秀的注释就是表达意思明确,引用地方或者使用地方限制说明准确,糟糕的就是注释让人看不懂

    2024-01-08 13:37:31
    赞同 4 展开评论 打赏
  • 1 我遇到的优秀注释就是 注释内容不长,但是注意点很明确,一条一条罗列,意思表达简单明了的那种

    2024-01-08 13:28:01
    赞同 3 展开评论 打赏
  • 1、工作中你遇到过的糟糕注释或优秀注释有哪些?
    经常遇到,非常依赖程序员的水平,糟糕注释居多,大多数的注释都是很简单,只有自己知道的那种
    2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
    最好是团队有个明确的规范,对代码命名,格式等做出要求,这样就可以减少一些注释也能让团队中的人明白意思

    2024-01-08 13:23:40
    赞同 2 展开评论 打赏
  • 2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
    我觉得尽量还是要多注释,这个比较看程序员的阅读代码的水平,正常的做法就是对一些命名能够有含义,对代码结构进行拆解,不要全部写在一起

    2024-01-08 13:21:17
    赞同 2 展开评论 打赏
  • 1 有遇到过,经常能碰到一些注释是反人类的,注释内容非常长,看的头晕的那种,这种是见过最糟糕的注释

    2024-01-08 13:20:09
    赞同 2 展开评论 打赏
  • 1、工作中你遇到过的糟糕注释或优秀注释有哪些?
    有遇到过,大多数都是没有注释的,或者只写一两个字的那种

    2024-01-08 13:17:45
    赞同 2 展开评论 打赏
  • 1、工作中你遇到过的糟糕注释或优秀注释有哪些?
    糟糕注释一般有以下几种情况:
    1没有注释:缺乏注释或者完全没有注释,使得代码难以理解和维护。
    2冗长而无用的注释:注释内容过多,但没有提供实质性的信息,只是重复了代码本身已经表达的内容。
    3错误的注释:注释与代码不一致,或者过时的注释导致误导。
    4不规范的注释:注释使用拼写错误、语法错误,或者没有遵循团队约定和最佳实践。
    优秀注释:
    1解释代码意图:注释清晰地解释代码的目的、意图和设计思路,增强代码的可读性和可理解性。
    2提供上下文信息:注释提供与代码相关的上下文信息,例如输入输出格式、预期行为等,有助于理解代码的作用和用途。
    3说明算法或复杂逻辑:对于复杂的算法或逻辑,注释可以提供更详细的说明和解释,帮助他人理解代码的实现细节。
    4提醒和警示:注释可以用来提醒和警示其他开发者可能出现的问题、注意事项或潜在的风险。
    2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
    使用有意义的变量和函数命名:选择具有描述性的变量和函数名称,可以减少对注释的需求。通过命名清晰地表达代码的意图和功能。在代码中添加一些示例用法,可以帮助其他开发者更好地理解代码的使用方式和预期行为。

    2024-01-08 13:17:46
    赞同 2 展开评论 打赏
  • 2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
    在编写代码的时候下点功夫,比如函数命名的时候

    2024-01-08 13:11:31
    赞同 2 展开评论 打赏
  • 1 优秀注释的话就是那种一眼就知道这个函数的作用,入参出参明确;糟糕的就是,要么注释很少,要么注释不明确,要么就是更新不及时的注释

    2024-01-08 11:43:28
    赞同 2 展开评论 打赏
  • 1、工作中你遇到过的糟糕注释或优秀注释有哪些?
    只写一行简单注解,但内容同代码意思完全不符。
    2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
    注重代码结构和命名的可读性

    2024-01-08 11:41:04
    赞同 1 展开评论 打赏
  • 1、工作中遇到的糟糕注释:
    过于简单,只写“此处进行数据验证”但没有具体说明如何验证。
    过时或与代码实际功能不符,导致读者误解。
    注释过于冗长,描述过于详细,读起来很费劲。
    工作中遇到的优秀注释:
    清晰、简洁,能够准确描述代码功能或意图。
    适当使用中文注释,便于团队成员理解。
    描述算法或复杂逻辑时,会使用“首先...然后...最后...”等结构化语句。
    2、减少注释但依然能让他人看得懂代码的方法:
    编写有意义的变量名、函数名,使代码自解释。
    遵循一定的代码格式和规范,如函数/方法命名、缩进、空格等。
    在关键地方添加注释,解释为什么这样做,而不是仅仅描述代码做什么。
    使用有意义的空行和段落,将代码逻辑分区,便于阅读。
    编写单元测试和文档,通过测试用例解释代码行为,文档描述模块功能和接口。

    2024-01-07 21:29:46
    赞同 1 展开评论 打赏
滑动查看更多
问答分类:
问答地址:

话题讨论榜

  • 1
    在做程序员的道路上,你掌握了什么关键的概念或技术让你感到自身技能有了显著飞跃?
    奖品池:4000积分,腰靠垫*5,体脂秤*2
    80

    学习了设计模式,准确说是理解了面向接口编程之后,感觉才真正理解了面向对象的含义,才敢说"入门”了。 面向接口编程,其实是多个设计原则的融合,比如开闭原则、接口隔离原则和依赖倒置原则。 传递接口而非实现,就能在后续优化、运维时做到做小的影响。

  • 2
    如何处理线程死循环?
    奖品池:4000积分,小米随身音箱*2,计时器*5
    126

    线程死循环是指线程运行到某一条指令后,无法继续往下执行,循环一直执行该一条指令,导致整个系统的卡住的现象。 1、解决办法是使用gdb调试器,gdb可以帮助我们找出死循环的指令,并且可以监视线程的运行情况,这样我们就可以找出因为死循环造成程序卡住的原因。 2、简单粗暴法Stop 3、interrupt停止标记法

  • 3
    如何看待首个 AI 程序员入职科技公司?
    奖品池:4000积分,开发者定制T恤*5,咖啡杯*3
    94

    自从安装了通义灵码,确实得到了一些有益的效率提升,当然跟同事朋友们聊天,也有一些吐槽。 有益的: 在对已有代码进行优化时,可能是基于上下文(代码、注释等)的理解,给出的提示都非常有参考性; 用户体验上,现在在IDEA中就能直接使用,不用打开其他客户端,更加丝滑; 回答的连续性更加完整,对话的前后逻辑更加严谨,给出的答案也越来越准确。 吐槽的: 对于有些他不清楚的逻辑,往往会根据上下文胡乱提示...

  • 4
    作为一个经典架构模式,事件驱动在云时代为什么会再次流行呢?
    奖品池:4000积分,加湿器*2,腰靠垫*5
    92

    在云时代背景下,事件驱动架构(EDA)再次流行起来以下几个原因: 弹性和可扩展性:云计算提供了弹性和可扩展性的基础设施,使得事件驱动架构更容易实现。通过云服务提供商的资源扩展能力,可以根据需要动态地分配和释放计算资源,以满足事件的处理需求。 实时性和即时性:云时代要求系统能够实时地响应和处理大量的数据和事件。事件驱动架构通过异步和并行的方式处理事件,能够在实时性和即时性方面提供更好的性能。 ...

  • 5
    你认为一个优秀的技术PM应该具备什么样的能力?
    奖品池:4000积分,护颈枕*3,办公静音鼠标*3
    160

    1,沟通力; 2,前瞻的能力; 3,对技术的掌握; 4,对项目的逻辑认知; 5,组织规划能力; 6,对不同人群对象的共情力; 7,创新力; 8,领导力; 9,快速学习的能力; 10,目的导向,步骤倒推的能力等

  • 相关电子书

    更多
    低代码开发师(初级)实战教程 立即下载
    冬季实战营第三期:MySQL数据库进阶实战 立即下载
    阿里巴巴DevOps 最佳实践手册 立即下载