Code Comments

Posted on Friday, Jan 19, 2018
How often should you leave code comments? Is it necessarily a failure to express yourself clearly in the code? Are code comments the best way to communicate with your team? Are your comments helpful, or just cathartic?



  • Definition of comments: “Metadata in source code that describe what code fails to communicate. Some languages and frameworks opt to use the mechanism of comments as formal documentation for code, but these two concepts should be separated.
  • Strive to make code self-documenting
  • Formal Documentation vs. Code Comments
  • Using tests to document your code
  • Considering strong types as a type of documentation
  • Docstring Tests
  • The value of documenting types
  • Worthless comments should be avoided
  • Don’t use comments to “vent” your emotions
comments powered by Disqus