Rules for Code Comments

#opinion

Always motivate, always say why. Never forget to say why. Because if you explain the rationale for a decision, it not only increases the hearer's understanding, and makes them more likely to adhere or comply, but it also shares criteria with them with which to evaluate the decision and its importance.
-- tigerbeetle/docs/TIGER_STYLE.md at main · tigerbeetle/tigerbeetle · GitHub

My preferred style:

// NOTE (Name, Date): Message
// NOTE (JS, 22.08.25): This serves as an example
// I include the date, because comments often become stale when code changes, so if the code changed last week, but the comment is 2 years old, you should question its validity.

// I sometimes use other types of comments to separate ideas/topics. This makes it easier to search for and distinguish while skimming the code.
// TODO (Name, Date): What to do and why I did not do it instead of writing this. (need to have a good reason for putting off work for later)
// IDEA (Name, Date): A very vague idea (less concrete than a TODO), open for discussion
// OPTI (Name, Date): An optimization idea I reserve for later, because it is too complicated or not necessary for now

The comments inserted by AI tools are usually not useful, since they just explain what the code is doing - which is mostly trivially obvious when you read it. You should not copy this style:

// List of options to populate the dropdown
const optionsList = ['Option 1', 'Option 2', 'Option 3', 'Option 4'];

// Function to populate the dropdown
function populateDropdown(options) {
    const dropdown = document.getElementById('dynamicDropdown');

    // Clear any existing options
    dropdown.innerHTML = '';

    // Create and append options
    options.forEach(optionText => {
        const option = document.createElement('option');
        option.value = optionText.toLowerCase().replace(' ', '_'); // Example of setting value
        option.textContent = optionText;
        dropdown.appendChild(option);
    });
}

// Call the function to populate the dropdown with the list
populateDropdown(optionsList);

Good eamples: