3 ms·
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 outd
by soneca 8y ago
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
- nemetroid 8y agoThere'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.
- raarts 8y ago> 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)