News for hackers. Stuff that matters.
Re:Remove Half of Your Documentation by jjgreen on Friday October 13, 2023 @06:13AM (#37868924)
When the signs say "this is a road" every 20 feet, there's not much point to them.
Re:Remove Half of Your Documentation by vasco on Friday October 13, 2023 @06:26AM (#37868989)
Those signs usually say the current kilometer you are on the road, which is extremely useful to report accidents or damage to the road or surrounding structures with large accuracy. This was specially relevant before everyone had a GPS receiver in their pocket, but is still useful - it's still easier for police or firefighters to go to X km on some road then to a GPS waypoint as its easier to communicate verbally and more likely that people will immediately know how to get there. Not sure about every 20feet though, different countries have different distances (every 100 meters in some).
Re:Remove Half of Your Documentation by ff_ on Friday October 13, 2023 @06:17AM (#37868950)
Sure, but then the advice we should give is "please please document the WHY", rather than "stop commenting"

In any case, I personally find it very useful when I come to a new piece of code to find comments that summarise what it's happening in a few words without having to parse 10-100 lines of dense implementation - I have so much cognitive ability I can apply in one day, and any effort to optimise its usage should be welcome

Re:Remove Half of Your Documentation by plastic3169 on Friday October 13, 2023 @06:26AM (#37868992)
Until it snows a lot.
Re:Remove Half of Your Documentation by ReleaseCandidat on Friday October 13, 2023 @07:11AM (#37869282)
I've just learned a new english word: Delineator. Maybe you should too.
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.

Re:Remove Half of Your Documentation by baby on Friday October 13, 2023 @07:29AM (#37869393)
When the road doesn’t have a sign to say where it’s going or how fast you can go you’re ducked