Contents
What is the difference between commenting code and code documentation?
Code Documentation vs Code Comments Code comments: any meta text you put in source code. Code documentation: creating a conceptual maintenance manual for your source code (in the dictionary sense of documentation).
What is comments and documentation?
In source code files, comments having a certain form can be used to direct a tool to produce XML from those comments and the source code elements, which they precede. Comments using such syntax are called documentation comments. The output produced by the documentation generator is called the documentation file.
Which is better clean code comments or class documentation?
Comments which explains what an overly convoluted piece of code does is also a smell, but the fix is not to outlaw comments, the fix is the fix the code! In the real word, convoluted code does happen (hopefully only temporarily until a refactor) but no ordinary developer writes perfect clean code the first time.
What’s the difference between dry and clean comments?
There are two types of comments to consider – those visible to people with the code and those use to generate documentation. The type of comment that Uncle Bob is referring to is the kind that is only visible to people with the code. What he is advocating for is a form of DRY.
Why are comments usually correct when they are written?
Comments are, mostly, correct when written. However, code is dynamic and it’s likely that the code will change, either sooner or later. We might change the code because of changed business logic. However, tests don’t validate our comments. Did we also update them? Did we move the comment together with the code?
Why do you use comments in Java DocBlock?
A first reason to use comments is to document an API. In Java, it’s called Javadoc, in PHP Docblock and C# calls it “XML Documentation Comments”. They describe how the API’s should be used. We must realize that users of our API might not have access to our source code. Therefore, the documentation describes the expected input and output.