• 0 Posts
  • 8 Comments
Joined 1 year ago
cake
Cake day: June 24th, 2023

help-circle

  • Comment should describe “why?”, not “how?”, or “what?”, and only when the “why?” is not intuitive.

    The problem with comments arise when you update the code but not the comments. This leads to incorrect comments, which might do more harm than no comments at all.

    E.g. Good comment: “This workaround is due to a bug in xyz”

    Bad comment: “Set variable x to value y”

    Note: this only concerns code comments, docstrings are still a good idea, as long as they are maintained







  • ITT: People misinterpreting the idea as “facts that your school taught wrong”, when it’s really saying, “things that have changed since you went to school” (either through a change in definition or by new research).

    E.g. If you went to school before the early 2000’s, you were taught that Pluto is a planet, while that is no longer true since it was recategorized in 2006.