Reducing technical debt by valuing comments as much as code

Re:Reducing technical debt by valuing comments as much as code by Johnny555 on Tuesday January 31, 2023 @09:40PM (#34605644)

And also, the code can be clear and tell the truth along with the comment, while still being unhelpful:

  // Add with adjustment factor
  function AddWithAdj(int a, int b) { return a + b + 12345 }

When the function was written, everyone probably knew what the adjustment factor was for and how it was determined, but years later, someone's going to look at that code and have no idea.

[ Parent | on HN ]

Re:Reducing technical debt by valuing comments as much as code by another2another on Friday February 03, 2023 @07:51AM (#34640391)

>When the function was written, everyone probably knew what the adjustment factor was for and how it was determined, but years later, >someone's going to look at that code and have no idea

Well, to be fair that adjustment factor could be refactored to use a usefully named constant, with a helpful comment.

static const int ZEN_ADJUSTMENT = 12345; //When I wrote this only myself and God knew what this value meant, now...

int AddWithAdj(int a, int b) { return a + b + ZEND_ADJUSTMENT; }

[ Parent | on HN ]

Re:Reducing technical debt by valuing comments as much as code by Johnny555 on Saturday February 04, 2023 @08:21PM (#34660552)

  int AddWithAdj(int a, int b) { return a + b + ZEND_ADJUSTMENT; }

And now the maintainer is going to wonder why the originally programmer defined ZEN_ADJUSTMENT just above this function, but actually used ZEND_ADJUSTMENT (which is apparently defined somewhere else in the code). By design or typo!? :-)

[ Parent | on HN ]