News for hackers. Stuff that matters.
Re:Remove Half of Your Documentation by jjgreen on Friday October 13, 2023 @07:19AM (#37869327)
Re:Remove Half of Your Documentation by ReleaseCandidat on Friday October 13, 2023 @07:29AM (#37869394)
That's true, sorry, I didn't want to sound that aggressive.

Let me try again: have you ever experienced the importance of delineators when driving?

Re:Remove Half of Your Documentation by jjgreen on Friday October 13, 2023 @07:49AM (#37869527)
Actually no, I'm a city boy and use public transport. But delineators are not what I'm talking about, rather signs which say "this is a road" every 20 feet, those don't exist since they would be entirely pointless, like comments which mirror (hopefully) the line of code that follows.

There's a thing that happens when you start coding, you put comments next to the sharp corners to remind you what it does (because your code is obscure and non-obvious, you've just started doing this), then you want it to look tidy and professional, and occasional comments look unbalanced, asymmetric, so you add comments on the obvious bits to give a nice uniform look to it. You end up with

  // say hello
  printf("This is foo (version %s)\n", VERSION);
I'm as guilty of this as everyone else. The OP is saying try to avoid that, comments have a maintenance cost.
Re:Remove Half of Your Documentation by ReleaseCandidat on Friday October 13, 2023 @08:44AM (#37869953)
Oh, I'm not talking about comments, but literally road signs.

I've seen plenty of these comments myself in various states of correct- and usefulness (from right and helpful to redundant to wrong, because of a change to always been wrong) in the last (almost) 20 years. Some of them had been my own.