ToB企服应用市场:ToB评测及商务社交产业平台

标题: 程序员不撰写代码注释和文档的十大理由 [打印本页]

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

我们并非开发面向外部的 SDK，所以撰写文档似乎毫无必要。再者，写文档并不能作为 KPI 的一部分。
实际上，是因为工期过于紧迫。如果有充裕的时间，我甚至愿意增加单元测试。但现实是，刚刚完成一个项目，就有新的任务立刻接踵而至，没有时间让我们稍作休息。
有的时候，我们确实有文档，但却无法及时更新，全都是过时的内容。这种情况下，有文档反而不如没有，查阅文档往往不如直接看代码，但却让人误以为有文档就很方便。
在我的代码中，我几乎不写注释，API文档我会写在 wiki 中，代码规范，命名也规范。当你的代码规范、命名规范时，其实没有必要写注释。目录名、函数名和变量名就是最好的注释。
如果你的架构设计得很好，代码易读、易扩展，任何人都可以接手。这就让你成为一个“可有可无”的人。
如果你的代码写得很好，基本上没有 bug，而你又每天都不需要加班，你就被视为工作态度不积极的人。
如果你的代码写得很差，bug 层出不穷，每天都必须加班，你就成了公司的中坚力量。
如果你的架构一片混乱，除了你自己没有人敢接触你的代码，那你就是公司的重要人物，没有你，项目就会崩溃。
撰写文档和注释，需要体谅开发者的感受。正常的开发工时，我们至少需要一半的时间来写文档。如果没有这个时间，自然就不能写，这是毫无疑问的。
写注释是为了将来自己查看，而不是给后续接手的人看。如果自己都能看懂，就没必要写注释。代码的原则是：没有注释也能看懂的代码，才是最好的代码。

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

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

欢迎光临 ToB企服应用市场:ToB评测及商务社交产业平台 (https://dis.qidao123.com/)