A nice thread of discussing how to comment in code - http://groups.yahoo.com/group/extremeprogramming/message/74195 A Taxonomy Of Comments - http://blog.codefx.org/techniques/documentation/taxonomy-comments/ Everything have 2 sides - http://blog.codefx.org/techniques/documentation/comments-costs-benefits/ Example of comment haven't update freq enough - http://marxsoftware.blogspot.hk/2016/09/even-good-code-comments-deteriorate.html https://testing.googleblog.com/2017/07/code-health-to-comment-or-not-to-comment.html Putting comments in code: the good, the bad, and the ugly. - https://medium.freecodecamp.org/code-comments-the-good-the-bad-and-the-ugly-be9cc65fbf83