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.
[ Parent
| on HN ]
No need for the snark.
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?
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.