从此
📄文章 #️⃣专题 🌐上网 📺 🛒 📱

程序员要不要写代码注释和技术文档?

🕗2023-07-22
 欢迎来访!

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

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

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

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

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

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

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

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

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

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

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

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