The Shapes of Code

Re:The Shapes of Code by CraigJPerry on Tuesday January 28, 2020 @05:52AM (#22168172)

Like what? It can’t be the “how” - the code should be able to express that clearly. It can’t be the “what”, again that should be apparent from some combination of code and configuration / metadata.

So that leaves the “why”. To my mind, code comments are the worst place to record why a particular implementation exists. The why often needs collaboration with non-coders.

[ Parent | on HN ]

Re:The Shapes of Code by artsyca on Tuesday January 28, 2020 @06:08AM (#22168273)

It's definitely the why for any particular unorthodox bits like shims hacks workarounds and the like

The worst is finding some snippet from stack overflow or GitHub without a reference to the issue to back up why this thing is here or perhaps a TODO: with an improvement

[ Parent | on HN ]

Re:The Shapes of Code by minaa-chan on Tuesday January 28, 2020 @09:26AM (#22169605)

I disagree. The code is the best place to comment the why. Regardless of what is documented or what is written up on jira or w/e, the code is what is true.

Commenting the purpose of the code and maybe a link to some documentation allows a future reader to see if the code still fulfills the requirements.

[ Parent | on HN ]

Re:The Shapes of Code by CraigJPerry on Tuesday January 28, 2020 @04:59PM (#22174546)

The comments are very often not true, that's why there's so much push back

[ Parent | on HN ]

Re:The Shapes of Code by minaa-chan on Wednesday January 29, 2020 @11:27AM (#22182288)

So they should be updated the same as any other documentation. They're there to help. They don't need to be 100% infallible to be useful.

[ Parent | on HN ]