As a general rule, comments are bad. In addition to cluttering the code, comments become useless as code changes because often the comments are not changed when the code is changed.
- Food Code 2017 Recommendations of the United States Public Health Service Food and Drug Administration The Food Code is a model for safeguarding public health.
- Clean Code is divided into three parts. The first describes the principles, patterns, and practices of writing clean code. The second part consists of several case studies of increasing complexity. Each case study is an exercise in cleaning up code—of transforming a code base that has some problems into one that is sound and efficient.
- .Clean Code saves time.We can’t take a short-term view of software.We need to look at the lifespan of the application. ©Jeremy Clark 2015.
Usually if you find yourself needing to write a comment, it is because the code is not clear. There could be many reasons that the code is not clear, some of which were discussed in the previous posts about Robert C. Martin’s book, Clean Code. Try to train yourself to ask what you can do to clean up the code, before writing a comment, to eliminate its necessity.
Slides about Robert C. Martins book 'Clean Code: A Handbook of Agile Software Craftsmanship'. (PDF version) Slideshare uses cookies to improve functionality and performance, and to provide you with relevant advertising.
Sometimes the solution is simply better naming. If your function names are clear with their intent, if the action that they will perform is stated in the function’s name, a comment about its operation is unnecessary. Similarly, if objects are named descriptively (ie: fileAgeInDays), there should be no question about what the object is that the name is describing.
Rarely comments are necessary, but they can be useful for things like adding legal headers or footers, or when the intent of a function is not obvious. It might be helpful to comment non-plain English parts of the code such as a regular expressions. They can also serve as a note for something to come back to if something needs attention that could not be met at the time of writing.
Clean Code Pdf Download
There is not much to say about comments except to try to avoid them whenever possible. Clarify through better naming and smaller methods rather than commenting.