Logo: Relish

  1. Sign in

Project: Ruby-style-guide

Comments

Good code is its own best documentation. As you're about to add a
comment, ask yourself, "How can I improve the code so that this
comment isn't needed?" Improve the code and then document it to make
it even clearer.

-- Steve McConnell

  • Write self-documenting code and ignore the rest of this section. Seriously!

  • Write comments in English.

  • Use one space between the leading # character of the comment and the text
    of the comment.

  • Comments longer than a word are capitalized and use punctuation. Use one space after periods.

  • Avoid superfluous comments.

    # bad
    counter += 1 # Increments counter by one.
    
  • Keep existing comments up-to-date. An outdated comment is worse than no comment
    at all.

Good code is like a good joke - it needs no explanation.

-- Russ Olsen

  • Avoid writing comments to explain bad code. Refactor the code to make it self-explanatory. (Do or do not - there is no try. --Yoda)

Topics

  1. Comment Annotations

Last published over 6 years ago by David Kariuki.