Should You Comment Your Code?

Posted by jsonmez on Wednesday January 14, 2015 @12:54PM
from the simpleprogrammer.com dept.

http://simpleprogrammer.com/2014/02/13/comment-code/

( 7 comments | 2 points | on HN )

Re:Should You Comment Your Code? by _lce0 on Wednesday January 14, 2015 @01:22PM (#8888009)

Leaving aside code documentation (aka dockblocks), I can think of dozen of examples where you MUST comment you code..

  - strict order of execution
  - math formulas in the code (or its results)
  - external systems requirements/hacks
  - non-explicit side effects
  - legacy or costly known issues
  - intention of cryptic code
  - design choices (and its tradeoff)
  - ..

This obviously implies you actually care about who will maintain such best

[ Parent | on HN ]

Re:Should You Comment Your Code? by simonblack on Wednesday January 14, 2015 @07:38PM (#8890188)

Comments are an act of kindness towards the person who will be doing the maintenance on the code you have written. It's doubly kind when that code maintainer is yourself.

[ Parent | on HN ]

Re:Should You Comment Your Code? by hwgd on Wednesday January 14, 2015 @01:05PM (#8887912)

Commenting code only works if other people who change the code also bother to change the comments

[ Parent | on HN ]

Re:Should You Comment Your Code? by 0xDOOD on Wednesday January 14, 2015 @01:05PM (#8887911)

If you want to, yes.

If you don't, I feel sorry for whoever has to maintain your code.

[ Parent | on HN ]

Re:Should You Comment Your Code? by Randgalt on Wednesday January 14, 2015 @12:59PM (#8887872)

Rule #1 - Comments lie

[ Parent | on HN ]

Re:Should You Comment Your Code? by 0xDOOD on Wednesday January 14, 2015 @01:03PM (#8887895)

So can variable and function names, but comments are easier to update.

[ Parent | on HN ]

Re:Should You Comment Your Code? by jsonmez on Wednesday January 14, 2015 @01:01PM (#8887883)

Agree. Never trust them.

[ Parent | on HN ]