Five Lines of Code

8 Stay away from comments

This chapter covers

• Understanding the danger of comments
• Identifying comments that add value
• Dealing with different types of comments

Comments are probably one of the most controversial topics in this book, so let’s start by clearing up which comments we are talking about. This chapter considers comments that are inside methods and not used by external tools, like Javadoc:

interface Color {
  /**
   * Method for converting a color to a hex string.
   * @returns a 6 digit hex number prefixed with hashtag
   */
  toHex(): string;
}

Although controversial to some, my opinion aligns almost perfectly with those expressed by many brilliant programmers. Comments are an art form, but unfortunately, not many programmers study how to ...