Last Updated: February 25, 2016
· dideler

How to comment code

Way too often do I see code that is poorly commented. Here are some guidelines that I try to follow for comments:

  • Only describe how when complicated
  • Always describe what
    • Do this at the file/module, class, and function/method level
    • You can avoid doing it for functions/methods when they're very short or obvious
  • Describe why if not obvious
    • Which is most of the time
    • More important than what and how since you can eventually figure those out from reading the code
  • Use a style guide that covers comments and refer to it often

I'd love to hear suggestions for improving these guidelines!