Skip to content

Instantly share code, notes, and snippets.

@kimadeline

kimadeline/comment-guidelines.md

Last active February 18, 2021 23:42
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save kimadeline/ca086458c9be5d9a9d87dde2ef3150f0 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save kimadeline/ca086458c9be5d9a9d87dde2ef3150f0 to your computer and use it in GitHub Desktop.
Download ZIP
Comment guidelines
Raw
comment-guidelines.md

// The changes would go under the existing "Guidelines section"

Guidelines

Typing

< our current guidelines>

Comments

  • Add comments to explain non-obvious decisions, or contextual knowledge that can be forgotten.
  • Conciseness is important.
  • Comment should start with an uppercase letter, and end with a period.
  • If a question can be answered by looking at the code, a comment is probably unnecessary.
  • A comment should answer "Why was this done this way?" two years down the line. If it doesn't, it is probably unnecessary, or should be rewritten.
  • If some logic depends on external factors or tools, a comment capturing the assumptions made at implementation time may be useful.
  • If the comment refers to work that needs to be done, create an issue for it and link it in your comment.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment