News for hackers. Stuff that matters.
Re:Writing system software: code comments by soneca on Sunday October 07, 2018 @09:27AM (#18160426)
There is a middle way between code comments and "my code is self-explanatory" though, doesn't?

A problem with code comments is that it very easily becomes outdated. And if the same method keep changing for different reasons, the code comments might become rather long.

I believe a good practice is to avoid code comments and document the why in the commit messages and PR descriptions. This way is easy enough to git blame and go to the "why" whenever a code is not self-explanatory

Re:Writing system software: code comments by nemetroid on Sunday October 07, 2018 @02:54PM (#18162064)
There's a particularly good example of this risk in the article:

    /* Unlink the client: this will close the socket, remove the I/O
     * handlers, and remove references of the client from different
     * places where active clients may be referenced. */
    unlinkClient(c);
I wouldn't trust a comment as technically detailed as this one to stay in sync with code changes to unlinkClient.
Re:Writing system software: code comments by raarts on Monday October 08, 2018 @03:33AM (#18164956)
> a problem with code comments is that it very easily becomes outdated

That's a red flag for code reviews being absent. (Or badly performed)