Don't write lying comments and don't write comments that will encourage your successors to make lies of them.
When your successors make changes to the code, they need to be able to find the comments that must be updated. If your comments are disorganized or voluminous, they won't have the time.
Stream of consciousness comment writing is usually disorganized.
Comments that simply translate what the code says are voluminous and useless. Assume your successor can read the programming language.
Details in comment writing are not bad per se. The questions are
Affirmative answers to these questions by your code reviewers should mean your comments are worth keeping up to date as the code changes. Copyright and Permissions
This tip is distributed to individuals free of charge from the Sofware Build and Fix web site. All other distribution (including but not limited to internal distribution within an organization and mirroring of any kind) is forbidden without written consent of the copyright holder.
Return top of this document.