Clean Code - Comments Are Lies

API Docs

Effective API documentation is crucial for both internal and external users. Michael emphasizes the importance of tools like Javadoc for providing descriptions of method arguments and returns, which can be invaluable when working with packages that others will use 1. Joe adds that summary documentation should be included when packaging components for reuse, as it saves time and effort in the long run 1.

If it's something that a package or some sort of component that you've bundled that people are going to use, I do think you document those with comments or whatever, however you can generate the documentation.

--- Alan

Alan also highlights the value of auto-generating documentation from comments, as seen in frameworks like ExtJS, which can streamline the creation of comprehensive API documentation 2.

   

Commenting

Commenting practices in code can either aid or hinder developers. Alan points out that outdated or misleading comments are worse than no comments at all, as they can lead to incorrect assumptions about the code 3. Joe agrees, noting that the older a comment is, the more likely it is to be inaccurate 3.

Inaccurate comments are far worse than no comment at all, right? So that misinformation puts the developer in the wrong frame of mind.

--- Joe

Michael shares his frustration with comments that merely restate the obvious, such as JavaDocs that describe a variable as "the current date," which he finds redundant and unhelpful 4.