News for hackers. Stuff that matters.
Re:JSON as configuration files: please don’t (2016) by nine_k on Saturday April 13, 2019 @03:51PM (#19655346)
Comments are a code smell when they describe things that should be described in code.

Comments are important when they express things that code cannot.

Examples:

// See ticket XYZ-123 for discussion and rationale.

// We are sidestepping a bug in Docker 3.x here.

// TODO: Allow queue size per service version. Currently we're using max size for all.

Re:JSON as configuration files: please don’t (2016) by breck on Saturday April 13, 2019 @07:52PM (#19656560)
Great examples. I wonder though if all those could be better expressed using something like decorators in order to enforce some static time checks. For example, instead of a free form comment to do have a structured todo notation that then makes the todo parsible and checkable. Often I see a //todo comment that is still there by accident after the thing is done. Or a todo that has since been abandoned.