Every change to code must include a comment. The comment explains why the change was made. The comment helps future developers understand the code.
By Pawan Nayar · from the LLOS AI Learning record
Every change to code must include a comment.
The comment explains why the change was made. The comment helps future developers understand the code.
A developer must add a comment for every code change. The comment must include the date of the change. The date format is YYYY-MM-DD. The comment must explain why the change was made. It is not enough to just label the change. The comment should describe the problem the change solves. The comment should explain why a specific solution was chosen. It should also state what might break if the code is changed later. If there were past failures, the comment should mention them. For CSS, a developer should document other solutions that did not work. This prevents repeating past mistakes. This applies to all file types, like HTML, JavaScript, CSS, Python, and JSON.
A developer changes a JavaScript function. The developer adds a comment: `// [2024-07-20] This change fixes a bug where user data was not saving. The previous method used local storage, which caused data loss on refresh. Using session storage ensures data persists during the session. Changing this to local storage will cause data to disappear.`
More from the same record, pulled by shared topic — not written new for this page.
A developer must find all places where a problem might happen. The developer should list all these places.
Without a central plan, different parts of the software are built in different ways. This leads to many small problems that add up.
A project's test plan and all rules must be kept inside the project folder. This makes sure everyone working on the project can find them easily.
A developer must add a comment for every code change. The comment explains what changed, why, and what might break if removed.
Every change to code must include a comment. The comment explains why the change was made. The comment helps future developers understand the code.