Do You Need That Comment?

Updated: 2016-11-14

The next time you think about writing a 15 line comment, a comment that includes bullet points, a list or even a diagram, do yourself a favor and ask why you are writing it. It’s probably so that you and your teammates will have an easier time understanding that code later, which is great, because everyone loves easy to understand code, but why isn’t that code easy enough to understand without the comment? Are your models bad? Is the function doing too many things? Are your variables named poorly?

If you can honestly answer no to all of those questions, then go ahead and write your comment, but if not, consider making the code easier to understand instead of adding to the problem, everyone will love you for it.