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.
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