News for hackers. Stuff that matters.
Re:Please do not attempt to simplify this code by sridca on Thursday December 27, 2018 @07:47PM (#18773978)
Yea, but watch how soon it becomes outdated as the file changes.
Re:Please do not attempt to simplify this code by YorkianTones on Thursday December 27, 2018 @08:47PM (#18774285)
This. Documentation (comment blocks in code, as well as all other forms of documentation) tends to become outdated because it is not maintained in sync with every code change.

Solution: write clear, simple, modular code that is self-documenting and does not need extensive commenting.

Re:Please do not attempt to simplify this code by TeMPOraL on Friday December 28, 2018 @01:45AM (#18775225)
How soon? I've rarely seen it happen in a meaningful way (i.e. other than someone using automated refactoring on some name, and breaking some comment reference that wasn't written in a way the autorefactor tool could read). When it happens and you see it, you should fix it like any other bug.

Key trick is writing comments as close as possible to the code they affect. Then it's hard to miss affected comments if one's not doing a shoddy job.

Re:Please do not attempt to simplify this code by dllthomas on Friday December 28, 2018 @01:27PM (#18778485)
> Key trick is writing comments as close as possible to the code they affect. Then it's hard to miss affected comments if one's not doing a shoddy job.

That also helps it show up in a PR so it may be caught in code review. Even so, IME comments get missed enough that over time I can't be as confident as we'd like that they match the code.

I think it's also worth calling out that this key trick is not being applied in the recommendation up-thread, which asks for a block comment at the top of the module.

Re:Please do not attempt to simplify this code by tome on Friday December 28, 2018 @05:41AM (#18776040)
I've done it frequently myself when I've changed a line that I originally wrote myself in a way that invalidates a comment written directly above.
Re:Please do not attempt to simplify this code by atulatul on Friday December 28, 2018 @12:01AM (#18774982)
Overall liked the original post. But also liked what you said.

But here are a couple of Martin Fowler quotes (from his Refactoring book) I tend to follow:

“A heuristic we follow is that whenever we feel the need to comment something, we write a method instead.”

“Whenever I have to think to understand what the code is doing, I ask myself if I can refactor the code to make that understanding more immediately apparent.”

https://www.goodreads.com/author/quotes/25215.Martin_Fowler

Re:Please do not attempt to simplify this code by garmaine on Friday December 28, 2018 @04:37AM (#18775800)
Reject pull requests that don't update the documentation (and tests).