10、代码开发的实用指南

代码开发的实用指南

1. 代码中的有效沟通

在代码编写过程中，注释起着至关重要的作用。当代码过于复杂难以阅读时，注释应逐行解释代码的具体操作。然而，程序员通常讨厌编写文档，这是因为大多数文档与代码分离，难以保持更新，还可能违反DRY原则（不要重复自己），甚至导致误导性的文档，这往往比没有文档更糟糕。

代码文档有两种方式：一是通过代码本身，二是使用注释来传达非代码相关的问题。如果需要通读一个方法才能理解其功能，会花费大量时间和精力。而几行描述方法行为的注释则能让事情变得简单，能快速了解其意图、期望和注意事项，节省大量精力。

但并非所有代码都需要注释。源代码应通过优雅清晰的表达，如合理使用变量名、空白、逻辑分离和简洁表达来让人容易理解，而不是依赖注释。命名非常重要，精心选择的名称能向读者传达大量意图和信息，而人为的命名方案（如匈牙利命名法）会使代码难以阅读和理解。

一个好的名称应能向读者传达大量正确信息，糟糕的名称则毫无信息，甚至传达错误信息。例如，名为 readAccount() 的方法实际是将地址信息写入磁盘，这就是一个糟糕的命名。同时，应避免使用隐晦的变量名，像 foo 这样的临时变量名虽有历史意义，但无法传达作者意图。而一些传统的短变量名，如 i 作为循环索引变量、 s 作为字符串变量，在很多语言中是惯用的，不算隐晦。

此外，一些传达明显信息的注释，如类构造函数旁的 //Constructor ，不仅会给源代码增加噪音，还可能随时间变得不正确。许多注释并没有传达有用信息，如