`
wenjinglian
  • 浏览: 822600 次
  • 性别: Icon_minigender_1
  • 来自: 株洲->深圳
社区版块
存档分类
最新评论

请注释你那该死的代码

阅读更多

每次我遇到一个程序员——有时是相当高水的——总发现他会认为:你并不需要给你的代码加注释。我要说,这就是胡说八道。我很长时间以来一直这么表达。问题是,让事情改变要比你想象的难。虽然我们正处在努力编写那些讨厌的代码、准备发布一些会令人惊叹的新东西的紧要关头,我们仍然几乎注释所有的东西。没有任何借口不去做这些事情。每隔3到7行代码,你就能看到有长篇的社论发表。有时,几百行代码里,你就能找到一个很好的笑话。

错误的藏身之处

看,一个是你想要的,一个是你实现的。你的bug就在这两者之间。如果写了注释,你就是在告诉我你想要的。而你的代码中告诉我你是如何去做的。程序的缺陷要么存在于你想要的想法中,要么,需求是对的,而你的代码有问题。请帮助我,让我知道究竟是哪个错了。

不要偷懒

一个常见的反对声音是:我听说,注释经常会过期,因为代码会经常更新,而注释不会。你不更新注释吗?你的同事也不?不要偷懒,不要养成一个让人认为偷点儿懒无所谓的文化氛围。告诉同事你是如何一丝不苟的注释程序的,让他们知道你也希望他们这样去做。说不注释是因为怕某人或某些地方在将来会造成你的错误,这只是在找借口。

你是有经验的人

人本无知,这很自然,但你是有经验的人。因此,你有义务教育那些需要学习的人。你的注释会指导那些正在阅读你的代码的人。告诉他们为什么在这里要用Tuple数据结构,而不是用其它的(更好的做法是附加一个stack overflow或dotnetperls上的链接 … 你完全可以做到这些,不是吗?)你在这走了一个什么捷径?如果不走捷径你就不能按时发布,所以,告诉这些新手你遇到的特殊情况。否则的话,最终你的不好的代码将会被四处拷贝,四处散播。看!你写的烂代码变成了公司的程序模板!完全没有注释!

你会打字

我的招聘过程有一部分是白板编程,一部分是键盘编程。所有好的程序员都是打字高手。就说你每分钟能打出40-60词。那请你告诉我,为什么在你机枪扫射似的编写代码时不加上注释呢?当然,你可以花30秒时间告诉我,代码写的这样一团糟是因为搞业务的那个家伙需要程序在本周发布而换回不菲的7.5万美元。可是下个月呢?这些代码不要了?封存到石头里了?我知道这些代码是在干什么。但请告诉我你的意图

你在一天天变老

听我说,我编程已经很久了,也许早在你上中学之前。我仍然在编程,我仍然喜欢编程。有朝一日,你也会变的跟我一样老。如果你到了像我一样(那时我已经没有能力再教育你),那时,有太多的层,有太多的抽象,有太多的技术架构,你无法完全记住。你的注释就能出来指导你。它们会告诉你,6个月前,你是用这种方法、这种模式实现的,而且这样做只是为了炫耀。如果你是一个真正优秀——并且仍然在做编程的程序员——你会认识到,这些代码写的很烂,你现在需要以不同的方式重新实现它。而你仍然有你的注释来让你回忆起当时的想法和为什么这样做。

来源:外刊评论

[本文英文原文链接:Comment your damn code ]

 

分享到:
评论

相关推荐

    sourceinsight 代码行注释,去注释代码插件

    本文将围绕"sourceinsight 代码行注释,去注释代码插件"这一主题,详细介绍如何使用自定义宏来实现快速的代码注释和去注释操作。 首先,我们关注的是"代码行注释"。在编程中,注释是必不可少的一部分,它用于解释...

    代码注释率统计工具下载

    4. **集成到开发流程**:为了持续监控代码质量,你可以将`linecount`与持续集成(CI)工具结合,如Jenkins、GitLab CI/CD等,每次提交代码时自动运行注释率检查,确保注释的完整性。 5. **优化注释策略**:高注释率...

    java代码注释模板

    Java代码注释是编程实践中非常重要的一个环节,它有助于提高代码的可读性和维护性。在团队合作中,良好的代码...通过使用提供的"java代码注释模板",你可以确保你的Java代码注释既规范又易于理解,为团队协作提供便利。

    Eclipse 代码注释模板

    Eclipse是一款广泛使用的Java...尤其在团队协作项目中,标准化的注释有助于其他团队成员理解你的代码,减少沟通成本,提升整体开发效率。因此,熟悉并掌握Eclipse的代码注释模板配置是每个Java开发者必备的技能之一。

    小米便签源代码+注释

    【小米便签源代码+注释】是一款专为学习Java编程和理解软件开发流程的开发者提供的资源。这个压缩包包含了小米便签应用的完整源代码,并且每段代码都有详细的注释,使得初学者能够更好地理解和学习代码的实现逻辑。 ...

    去除源代码注释

    在编程世界中,源代码注释是极其重要的,它们提供了对程序逻辑的解释,帮助开发者理解和维护代码。然而,在某些特定情况下,如编译优化、代码混淆或仅需执行无注释版本时,可能需要去除源代码中的注释。本文将深入...

    Java代码注释率检查器.rar

    Java代码注释是编程实践中非常重要的一个环节,它有助于提高代码的可读性和维护性。注释能够解释代码的功能、用途以及实现逻辑,使得其他开发者能更快地理解代码,尤其在团队协作中更是不可或缺。本资源"Java代码...

    自主研发的批量保留路径清理代码注释工具

    聪哥创作的一款批量保留路径清理代码注释的工具,目前兼容大部分常见的代码注释,涵盖c、java、python、php、js、html、css、mysql、node、vue、ruby等常见编程项目的注释无损清理。 2023年8月19日更新日志: 1.对...

    程序员佛祖代码注释.txt

    程序员佛祖代码注释,佛祖保佑,代码无BUG

    VB代码注释器

    在传统的VB编程中,注释代码通常需要手动输入'(单行注释)或'_'(多行注释)符号,而VB代码注释器则提供了一键操作的功能,大大节省了开发者的时间。通过这个插件,你可以轻松地选中需要注释的代码段,点击相应的...

    PatchMatchNet 代码注释版 下载 (注释非常详细,代码结构有所调整,使用起来更方便)

    PatchMatchNet 代码注释版 下载 (注释非常详细,代码结构有所调整,使用起来更方便) PatchMatchNet 代码注释版 下载 (注释非常详细,代码结构有所调整,使用起来更方便) PatchMatchNet 代码注释版 下载 (注释...

    代码注释检测工具,用于进行代码注释统计

    代码注释是编程实践中至关重要的一个环节,它有助于提高代码的可读性和可维护性。在软件开发过程中,良好的代码注释能够帮助团队成员更好地理解代码逻辑,减少误解,提高协同效率。本话题将深入探讨代码注释检测工具...

    代码 辅助 注释

    代码 辅助 注释 代码 辅助 注释代码 辅助 注释代码 辅助 注释代码 辅助 注释

    代码注释图形工具(字符画生成工具)

    在IT行业中,代码注释和图形工具是程序员和开发者日常工作中不可或缺的部分。这些工具帮助他们更好地理解代码逻辑,提升团队协作效率,同时增加代码的可读性和可维护性。本篇将详细介绍“代码注释图形工具(字符画...

    几种常用的注释 和 利用工具替换注释代码

    本文将详细探讨几种常用的注释类型,并介绍如何利用工具来替换注释代码。 首先,我们来看最常见的几种注释方式: 1. 单行注释: 在大多数编程语言中,单行注释通常使用特定的符号来开始。例如,在JavaScript、...

    代码注释对齐Visual Studio AddIn

    【代码注释对齐Visual Studio AddIn】是一种增强开发效率的工具,专为Microsoft Visual Studio集成开发环境(IDE)设计。Visual Studio AddIn是Visual Studio的一种扩展机制,允许开发者自定义IDE的功能,以满足特定...

    C/C++/Java 源代码注释清除工具

    标题中的"C/C++/Java 源代码注释清除工具"是一个专门针对这三种编程语言设计的实用程序,它的主要功能是移除源代码文件中的注释。在软件开发过程中,注释对于理解和维护代码至关重要,但在特定情况下,如代码混淆、...

    申请软著代码整理工具,快速清除代码中注释

    【标题】"申请软著代码整理工具,快速清除代码中注释" 描述了一款针对软件著作权(软著)申请而设计的代码处理工具。在软件开发过程中,代码注释对于理解和维护源代码至关重要,但在申请软著时,通常需要提交不包含...

    批量注释工具源代码

    在IT行业中,源代码的注释是至关重要的,它能够帮助开发者理解代码的功能、用途以及实现方式。批量注释工具的出现,极大地提高了代码维护和团队协作的效率。本项目提供的"批量注释工具源代码"是用C#语言编写的,主要...

    C++代码文档生成器 根据代码及注释自动生成代码文档.zip

    C++代码文档生成器是一种工具,它能够自动分析C++源代码,并基于代码中的注释生成详细的文档。这种工具在软件开发过程中非常有用,因为它可以帮助开发者快速了解代码结构,节省了手动编写文档的时间,同时也确保了...

Global site tag (gtag.js) - Google Analytics