re: Good comments explain WHY, not WHAT, and 3 more rules on writing good comments VIEW POST

TOP OF THREAD FULL DISCUSSION
re: I highly recommend taking a look at Clean Code by Robert C. Martin (a.k.a. Uncle Bob). The author argues there's no such thing as good comments as...
 

i don't buy the "good code doesnt need comments" anymore

even the best code can't explain oddities in partner libs or complicated domain logic

and i have yet to meet a company that never changes it's product and achieves "best code" over a longer time.

code has several dimensions:

  • the file / component (what a it does)
  • the system interconnection (how stuff fits together)
  • the product usecases (how users actually use it / domain logic)
  • the changes over time (legacy / pivots etc)

good code can explain the first dimension
barely the second
hardly the 3rd
almost never the 4th

thus: "explain why not what"

 

I agree for the most part that you should explain the "why not what" but of the four things you list above, you might argue that

  1. What it does - agree

  2. System interconnection does not belong in the comments unless it that part of the code is orchestrating the interconnection and the code is unable to make that clear. Comments like "This will be use by x for y" may not be useful as other components using this code may change what they do leaving the comment stale.

  3. Product usecases are really not appropriate for a comment in my view unless they are used directly to build/generate the documentation (for example using a tool like Docular).

  4. Changes over time - If done wrong this can leave a lot of stale information in the source that someone skimming over might draw incorrect conclusions from. If it is felt there is a need to write this is the code in comments it suggests to me that the commit log is not being maintained well for that code. Good commit log messages leads to a good story of what changed and why. I'd argue that writing good commit messages is more important with respect to changes over time.
    As a side note, for this if using git, learn interactive rebasing... it is in my view the path to a readable commit log.

code of conduct - report abuse