如何正确地给代码写注释？
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 积分的奖励。
注:楼层需为有效回答(符合互动主题)，灌水/复制回答将自动顺延至下一层。如有复制抄袭、不当言论等回答将不予发奖。阿里云开发者社区有权对回答进行删除。获奖名单将于活动结束后5个工作日内公布，奖品将于7个工作日内进行发放,节假日顺延。
参与讨论
-
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
1、工作中你遇到过的糟糕注释或优秀注释有哪些？
遇到过完全没有注释、注释和代码毫无关系、离职的人给后人留下的大坑
2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗？
建立规范化的代码体系、构建一本账管理对相关代码建立索引机制2024-01-09 19:11:44赞同 24 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
1、工作中你遇到过的糟糕注释或优秀注释有哪些？
完全不写注释。方法名 参数名随意
注释与代码不一致，留下过时的注释导致误导。
注释使用拼写错误、语法错误，或者没有遵循团队约定。
2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗
良好的命名和自解释的代码,使用正确的英文单词命名
2024-01-09 10:54:50赞同 17 展开评论 打赏 -
一万年太久，只争朝夕。2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
注释的目的是为了解释代码的功能、实现思路、注意事项等，提升代码的可读性和可维护性。
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 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
糟糕的注释：
# 增加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 + num22. 模块化和函数化：
# 糟糕的注释 # 处理用户输入，验证并保存到数据库 # ... # 验证邮箱格式是否正确 # ... # 保存用户信息到数据库 # ... # 优秀的注释 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 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
1、工作中你遇到过的糟糕注释或优秀注释有哪些？
糟糕的例子：//注释“某年某月谁改的“
OS 这名字都不知道是否还在这个碳基世界，目前的形态是碳基还是炭集，写的这个鬼注释仿若大圣五指山前留得那个记号，有个浮云用。
优秀：//存在原因+参数应用范围+举例2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗
难办难办 经常看到一个代码写得一塌糊涂，注释乱七八糟，观者恨不得问候代码创造者，发现出自己手。
不然就像word插入注释一般，又影增加冗余响速度。2024-01-08 14:30:52赞同 9 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
2有一些方法可以减少注释，但依然能让他人看懂代码：
使用有意义的变量和函数命名：选择具有描述性的变量和函数名称，可以减少对注释的需求。通过命名清晰地表达代码的意图和功能。
模块化和函数化：将代码分解为小的模块和函数，每个模块和函数只关注单一的功能，减少代码的复杂性和理解难度。
编写自解释的代码：通过良好的代码结构、逻辑和设计模式，使代码本身尽可能地清晰地表达其意图和功能。
添加文档注释：在函数和类的开头，使用适当的文档注释（如Javadoc或Python的docstring）来描述函数的输入、输出和功能。
提供示例代码：在代码中添加一些示例用法，可以帮助其他开发者更好地理解代码的使用方式和预期行为。2024-01-08 13:46:19赞同 5 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
2减少注释但保证可读的方法,我会:
注重代码结构和命名的可读性。使用自 explanatory 的函数/变量名字。
注释重要的逻辑变化或 boundary case。
注释公共库或复杂算法。
加入必要的测试用例。
保持简洁高效的代码风格。
2024-01-08 13:46:18赞同 5 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
糟糕的注释可能包括以下几种情况：
没有注释：完全没有注释，或者只有少量的注释，导致代码缺乏解释和文档，使得其他开发者难以理解代码的意图和功能。
冗长而无用的注释：注释内容过多，但没有提供实质性的信息，只是重复了代码本身已经表达的内容。这样的注释会增加代码的冗余，降低可读性。
错误的注释：注释与代码不一致，或者过时的注释导致误导。如果注释不反映实际的代码逻辑或者没有及时更新，那么将给其他开发者带来困惑和错误的理解。
不规范的注释：注释使用拼写错误、语法错误，或者没有遵循团队约定和最佳实践。不规范的注释会给阅读者带来困惑，降低代码的可读性和专业性。
过度注释：在每一行或每一个语句都添加详细注释，而这些注释对于理解代码并无实际帮助。过度注释会干扰代码的阅读，使得代码显得混乱。
单行注释过长：单行注释过长，超过一定的长度限制，难以阅读。注释应该简洁明了，提供必要的信息，避免过度冗长。
2024-01-08 13:47:13赞同 5 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
1有遇到过，很多时候都是忘记注释了，然后后期连自己都忘了是啥意思了
2024-01-08 13:46:54赞同 5 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
1 优秀的注释就是表达意思明确，引用地方或者使用地方限制说明准确，糟糕的就是注释让人看不懂
2024-01-08 13:37:31赞同 4 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
1 我遇到的优秀注释就是 注释内容不长，但是注意点很明确，一条一条罗列，意思表达简单明了的那种
2024-01-08 13:28:01赞同 3 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
1、工作中你遇到过的糟糕注释或优秀注释有哪些？
经常遇到，非常依赖程序员的水平，糟糕注释居多，大多数的注释都是很简单，只有自己知道的那种
2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗？
最好是团队有个明确的规范，对代码命名，格式等做出要求，这样就可以减少一些注释也能让团队中的人明白意思2024-01-08 13:23:40赞同 2 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗？
我觉得尽量还是要多注释，这个比较看程序员的阅读代码的水平，正常的做法就是对一些命名能够有含义，对代码结构进行拆解，不要全部写在一起2024-01-08 13:21:17赞同 2 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
1 有遇到过，经常能碰到一些注释是反人类的，注释内容非常长，看的头晕的那种，这种是见过最糟糕的注释
2024-01-08 13:20:09赞同 2 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
1、工作中你遇到过的糟糕注释或优秀注释有哪些？
有遇到过，大多数都是没有注释的，或者只写一两个字的那种2024-01-08 13:17:45赞同 2 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
1、工作中你遇到过的糟糕注释或优秀注释有哪些？
糟糕注释一般有以下几种情况：
1没有注释：缺乏注释或者完全没有注释，使得代码难以理解和维护。
2冗长而无用的注释：注释内容过多，但没有提供实质性的信息，只是重复了代码本身已经表达的内容。
3错误的注释：注释与代码不一致，或者过时的注释导致误导。
4不规范的注释：注释使用拼写错误、语法错误，或者没有遵循团队约定和最佳实践。
优秀注释：
1解释代码意图：注释清晰地解释代码的目的、意图和设计思路，增强代码的可读性和可理解性。
2提供上下文信息：注释提供与代码相关的上下文信息，例如输入输出格式、预期行为等，有助于理解代码的作用和用途。
3说明算法或复杂逻辑：对于复杂的算法或逻辑，注释可以提供更详细的说明和解释，帮助他人理解代码的实现细节。
4提醒和警示：注释可以用来提醒和警示其他开发者可能出现的问题、注意事项或潜在的风险。
2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗？
使用有意义的变量和函数命名：选择具有描述性的变量和函数名称，可以减少对注释的需求。通过命名清晰地表达代码的意图和功能。在代码中添加一些示例用法，可以帮助其他开发者更好地理解代码的使用方式和预期行为。2024-01-08 13:17:46赞同 2 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗？
在编写代码的时候下点功夫，比如函数命名的时候2024-01-08 13:11:31赞同 2 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
1 优秀注释的话就是那种一眼就知道这个函数的作用，入参出参明确；糟糕的就是，要么注释很少，要么注释不明确，要么就是更新不及时的注释
2024-01-08 11:43:28赞同 2 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
1、工作中你遇到过的糟糕注释或优秀注释有哪些？
只写一行简单注解,但内容同代码意思完全不符。
2、你有什么可以减少注释，但依然能让他人看得懂代码的方法吗？
注重代码结构和命名的可读性2024-01-08 11:41:04赞同 1 展开评论 打赏 -
2000元阿里云代金券免费领取，2核4G云服务器仅664元/3年，新老用户都有优惠，立即抢购>>>
1、工作中遇到的糟糕注释：
过于简单，只写“此处进行数据验证”但没有具体说明如何验证。
过时或与代码实际功能不符，导致读者误解。
注释过于冗长，描述过于详细，读起来很费劲。
工作中遇到的优秀注释：
清晰、简洁，能够准确描述代码功能或意图。
适当使用中文注释，便于团队成员理解。
描述算法或复杂逻辑时，会使用“首先...然后...最后...”等结构化语句。
2、减少注释但依然能让他人看得懂代码的方法：
编写有意义的变量名、函数名，使代码自解释。
遵循一定的代码格式和规范，如函数/方法命名、缩进、空格等。
在关键地方添加注释，解释为什么这样做，而不是仅仅描述代码做什么。
使用有意义的空行和段落，将代码逻辑分区，便于阅读。
编写单元测试和文档，通过测试用例解释代码行为，文档描述模块功能和接口。2024-01-07 21:29:46赞同 1 展开评论 打赏
版权声明：本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
话题讨论榜
OpenAI最新发布的支持实时语音对话的模型GPT-4o，被视为AI技术领域的一个重要里程碑。以下是几个关键点，总结了各界对GPT-4o的评价和看法： 技术创新 ：GPT-4o通过引入多模态交互能力，实现了在语音、视频及文本上的实时推理，这种全面的交互方式极大地提升了用户体验，被称赞为“更像人”的人工智能模型。它的“全模态”特性标志着AI人机交互进入了一个新的自然和流畅的阶段。 性能提升 ：...
图像生成类应用应当采取哪些策略来留住用户，确保其长远发展呢？ 增加多风格，富有趣味性的设置及个性鲜明的图像输出来提升产品的个性化，及趣味性，来吸引更多的用户更宽的用户群广覆盖提升使用率及用户群体数量
程序员害怕频繁改动需求，通常是因为以下几个原因： 工作量增加 ：每次需求变更都意味着之前的工作可能需要调整，甚至推倒重来，这直接增加了程序员的工作负担和时间成本。 项目延期风险 ：需求变动可能导致项目进度计划被打乱，原定的时间线难以维持，项目延期的风险增加。 设计与架构受影响 ：初期的设计和系统架构往往是基于既定需求制定的，频繁改动需求可能导致原有设计不再适用，需要重新规划，这不仅技术上复杂...
AI面试确实给求职者带来了新的挑战,我认为主要体现在以下几个方面: 人际互动的缺失 与人工智能面试官交流,缺乏面对人类面试官时的自然互动和沟通感受。这可能会让求职者感到孤独和不安,难以展现真实的自己。 压力与焦虑加剧 面对预设算法的层层考验,求职者必须时刻保持高度警惕和专注,以应对AI面试官的各种问题和测试。这会大大增加求职者的压力和焦虑感。 应试技巧的重要性 为了通过AI面试,求职者必须掌...
前言 在全行业数字化转型的时代，事件驱动架构再次成为热门话题，引起了技术圈广泛的关注和讨论，事件驱动架构正在迅速扩大应用范围，并成为 Gartner 年度十大技术趋势之一。根据预测，越来越多的新型数字化商业解决方案选择采用EDA架构，预计将有60%的解决方案采纳该架构。作为一个经典的架构模式，事件驱动在云时代为何再次流行起来成为焦点呢？本文就来简单分享一下其中的原因，解析事件驱动架构在云时代...
