loading...

re: Don't document your code. Code your documentation. VIEW POST

FULL DISCUSSION
 

There are a few reasons why I consider comments important:

  • languages are ambiguous, or lacking in semantic clarity. A perfectly formed algorithm may not always reveal what it's attempting to do, rather only how it is done.
  • How something is done, or what is happening, is not always enough to understand why the function would be called in the first place. Though I agree with nice function names, I disagree with names that are 80-100 characters long. Short of those lengths there will always be some uncertainty in the function's purpose.
  • Functions don't live on their own, they exist in a framework. Describing how this function fits into the framework is something that code alone cannot always do. This becomes more important as frameworks become more generic or abstract.
code of conduct - report abuse