Some issues to note when writing Ruby code comments _ruby Topics

Write it out of the interpretation document code and let this part rest. It's not about playing.
Use English to write notes.
Use a space to separate annotations from symbols.
Note more than one word should be capitalized and punctuation should be used. Use a space after a period

Avoid redundant annotations.

  # bad
  counter = 1 # increments counter by one

Updating comments at any time, with no annotations better than expired annotations.

Don't write comments for bad code. Refactor them so that they can be "self explanatory." (Do or do not-there are no try.)

Annotations should be written immediately above the relevant code.
The annotation keyword is followed by a colon and a space, followed by a record describing the problem.

If you need more than one line to describe the problem, subsequent lines need to indent two spaces behind the #.

  def Bar
   # Fixme:this has crashed occasionally since v3.2.1. It May
   # is related to the Barbazutil upgrade.
   Baz (: Quux) End
  

If the problem is obvious, then any document is redundant, and annotations can be (violated) at the end of the line without any comments. This usage should not be used in general and should not be a rule.

  def Bar Sleep
   # OPTIMIZE End
  

Use TODO to comment on missing features or features added later.

Use Fixme to note the code that has a problem to fix.

Use OPTIMIZE to note slow or inefficient code that can cause performance problems.

Use HACK to note that places that use the problem code may need to be refactored.

Use REVIEW to comment on those code that needs to be reviewed repeatedly for known good. For example: REVIEW: Are you sure the client is doing the right thing with X?

Use other custom keywords if you think it is appropriate, but make sure it is indicated in your project's README or similar place.