程序员不撰写代码注释和文档的十大理由

简介: 在软件开发的世界中,撰写代码注释和文档通常被认为是一项重要的工作,它可以帮助其他开发者理解你的代码,更容易地维护和扩展它。然而,在实际操作中,很多程序员却选择不写注释或文档。以下列出了程序员们在实践中经常提到的十大理由,这些理由不仅揭示了他们对于撰写文档和注释的观点,也反映出软件开发行业中一些深层次的问题。

在软件开发的世界中,撰写代码注释和文档通常被认为是一项重要的工作,它可以帮助其他开发者理解你的代码,更容易地维护和扩展它。然而,在实际操作中,很多程序员却选择不写注释或文档。以下列出了程序员们在实践中经常提到的十大理由,这些理由不仅揭示了他们对于撰写文档和注释的观点,也反映出软件开发行业中一些深层次的问题。

图片.png

  1. 我们并非开发面向外部的 SDK,所以撰写文档似乎毫无必要。再者,写文档并不能作为 KPI 的一部分。

  2. 实际上,是因为工期过于紧迫。如果有充裕的时间,我甚至愿意增加单元测试。但现实是,刚刚完成一个项目,就有新的任务立刻接踵而至,没有时间让我们稍作休息。

  3. 有的时候,我们确实有文档,但却无法及时更新,全都是过时的内容。这种情况下,有文档反而不如没有,查阅文档往往不如直接看代码,但却让人误以为有文档就很方便。

  4. 在我的代码中,我几乎不写注释,API文档我会写在 wiki 中,代码规范,命名也规范。当你的代码规范、命名规范时,其实没有必要写注释。目录名、函数名和变量名就是最好的注释。

  5. 如果你的架构设计得很好,代码易读、易扩展,任何人都可以接手。这就让你成为一个“可有可无”的人。

  6. 如果你的代码写得很好,基本上没有 bug,而你又每天都不需要加班,你就被视为工作态度不积极的人。

  7. 如果你的代码写得很差,bug 层出不穷,每天都必须加班,你就成了公司的中坚力量。

  8. 如果你的架构一片混乱,除了你自己没有人敢接触你的代码,那你就是公司的重要人物,没有你,项目就会崩溃。

  9. 撰写文档和注释,需要体谅开发者的感受。正常的开发工时,我们至少需要一半的时间来写文档。如果没有这个时间,自然就不能写,这是毫无疑问的。

  10. 写注释是为了将来自己查看,而不是给后续接手的人看。如果自己都能看懂,就没必要写注释。代码的原则是:没有注释也能看懂的代码,才是最好的代码。

图片.png

以上是程序员们不写代码注释和文档的十大理由,这些理由充分反映出他们在实际工作中的困扰和压力。但是,这并不意味着我们就可以忽视文档和注释的重要性。尽管在某些情况下,这些理由可能有一定的道理,但是好的代码注释和完善的文档无疑可以使我们的工作更加有效率,使其他开发者更容易地理解和维护我们的代码。为此,我们需要寻找一个平衡点,以满足项目的需求,同时也尽可能地减少对开发者的负担。

目录
相关文章
|
消息中间件 SQL 存储
超详细的RabbitMQ入门,看这篇就够了!
RabbitMQ入门,看这篇就够了
217011 68
|
Python
Python中如何按行遍历DataFrame
听世界的意见,保留自己的态度。
2253 0
|
算法 数据处理 数据库
生物学经典Blast序列比对算法原理,如何在R语言和Python中实现序列的比对分析?
生物学经典Blast序列比对算法原理,如何在R语言和Python中实现序列的比对分析?
端口被占用?两步解决端口占用问题
端口被占用?两步解决端口占用问题
1352 0
|
弹性计算 安全 Java
关于如何将Web项目部署到阿里云ecs服务器-5个步骤搞定
关于如何将Web项目部署到阿里云ecs服务器-5个步骤搞定
关于如何将Web项目部署到阿里云ecs服务器-5个步骤搞定
|
JavaScript
layUI下使用jQuery
layUI下使用jQuery
179 0
|
小程序
【经验分享】使用swiper组件制作文字上下滚动播报效果
【经验分享】使用swiper组件制作文字上下滚动播报效果
537 7
|
数据挖掘 atlas 数据库
TCGA数据挖掘 | Xena - TCGA数据下载
TCGA数据挖掘 | Xena - TCGA数据下载
645 1
|
数据库
利用massdatabase包提取物种KEGG通路与基因/化合物对应信息
最近手头处理一批代谢组数据, 想基于几十个关键差异代谢物代谢物进行下KEGG富集,能想到有两种方式解决,一种常用方式就是基于MetaboAnalyst在线富集,另一种就是解析出该物种的通路与代谢物的对应关系文件,然后用Y叔叔的Clusterprofiler包富集。经一番搜索,massdatabase包可帮我们轻松获得这个文件。 作者:凯凯何_Boy 链接:https://www.jianshu.com/p/654784925903 来源:简书 著作权归作者所有。商业转载请联系作者获得授权,非商业转载请注明出处。
699 1
|
数据可视化 数据挖掘
PCA 解释方差骤降图(ElbowPlot)拐点的量化识别
本文分享了一种在R语言里面实现量化识别 PCA方差贡献肘部图(ElbowPlot)中拐点 的简单方法,以供学习参考 定
1781 0