开发者社区 问答 正文

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

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 2624 分享 版权
167 条讨论
参与讨论
取消 提交讨论
  • 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
    你是怎么使用K8s的?
    奖品池:4000积分,指尖陀螺*3,K8s技术书籍*3,社区定制鼠标垫*3
    70

    在说起k8s的一些方便之处以及强大的应用场景来说,首先需要知道什么是k8s,那么什么是k8s呢?k8s是一个为容器服务而生的一个可移植容器的编工具,是一个管理应用的全生命周期的一个工具,从创建应用,部署应用,应用提供服务,扩容缩容应用,应用更新等都非常的方便,而且遇到一个服务器挂了,可以自动将这个服务器上的服务调度到另外一个主机上进行运行,无需进行人工干涉,这就是k8s的魔力所在。 相较于传...

  • 2
    Kimi-K2-Instruct 开了挂一般的推理和调用,底层魔法是什么?
    奖品池:4000积分,小夜灯*5
    82

    从“省心”到“放心”:Kimi-K2-Instruct推理与调用的3个“贴心”技术逻辑 前几天帮刚入行的实习生做“小众香薰产品推广方案”,我故意只丢了句模糊需求:“帮我把这个产品的推广思路理清楚,顺便看看能不能落地”——没想到Kimi-K2-Instruct没追问“要哪些维度”“要什么数据”,反而先列出“市场空白点(小众香薰用户增速18%)→竞品短板(多数缺场景化营销)→推广路径(线上小红书...

  • 3
    如何利用 AI 提升数据库运维效率?
    奖品池:4000积分,淘公仔1个(随机)*5
    83

    借力AI破局数据库运维困境:从DAS Agent看智能运维的效率革命 在云数据库广泛应用的今天,运维工作早已不是“监控指标、排查故障”这么简单——面对突发的CPU突增、隐蔽的性能瓶颈,传统依赖人工经验的运维模式往往陷入“响应慢、诊断浅、优化难”的困境。而AI技术的出现,正为数据库运维注入“自治能力”,让运维从“被动救火”转向“主动保障”。阿里云DAS Agent作为融合大模型与实战经验的智能...

  • 4
    数据存储阶段,哪些小妙招有助于优化成本
    奖品池:4000积分,龙蜥钥匙扣公仔*5,手机支架*5
    76

    多元数据治理方法: 数据分类与标准化: 对数据进行分类,制定统一的数据标准和格式,确保数据的一致性和可比性。 元数据管理: 利用元数据管理工具来记录数据的属性、来源、使用情况等信息,便于数据的检索和分析。 数据质量管理: 实施数据质量控制流程,包括数据校验、清洗、去重等,确保数据的准确性和可靠性。 数据安全与合规性: 遵守数据保护法规,实施数据加密、访问控制、审计日志等安全措施。 数据目录和...

  • 5
    “数据超人”MCP工具,到底是怎么让数据‘燃’起来的?
    奖品池:4000积分,电蒸锅*3
    17

    亲历 MCP 赋能可视化 OLAP 智能体应用:重构数据分析路径,破解企业效率瓶颈 在实际操作 “MCP 赋能可视化 OLAP 智能体应用” 方案的过程中,其对传统数据分析流程的重构能力、对不同角色需求的适配性,以及在大数据场景下的稳定表现,让人切实感受到 “从数据到价值” 的转化效率提升。以下从实际体验中的核心突破点、可深化优化的方向两方面,分享具体感受: 一、核心突破点:直击传统数据分析...

  • 还有其他疑问?
    咨询AI助理