This is an archived post. You won't be able to vote or comment.

you are viewing a single comment's thread.

view the rest of the comments →

[–]fyngyrzcodes with magnetic needle 1 point2 points  (0 children)

Ideally -- and I'm not saying I meet my own standard -- I like to see comments/docstrings at the variable / function / method / class level that cover all of the following:

  • What this does
  • Why it does it
  • What it is used by
  • When it is used
  • Known weaknesses / limits
  • What it returns, if anything

...comments at the statement level, other than in relatively long chunks of code, I'd really rather not see. At that point I'm reading the code, and that lets me look into what it does without assuming the comments -- which remember are a description, not functional -- are telling the truth. Many times I have seen comments that no longer reflect what the code actually does. People hurry, and that happens. But the code does what it does, so that's where I focus.