- only document the "why" (the intent and motivation). The code itself should be documentation of the "what" in most cases > **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](https://github.com/tigerbeetle/tigerbeetle/blob/main/docs/TIGER_STYLE.md) - if you had to rewrite a piece of code 3 times before it worked, write about what made it so difficult - if you had to google or read documentations for a day before a piece of code worked, write about what made it so difficult and link the documentation/stack overflow result - if a piece of code is much more complex than expected (Bullshit detector) write about the reason (or better: rewrite the code to be simpler) - if you had a profound insight or learning while writing some code, leave a comment about it - write about edge cases, that are easily missed (or better: write a test for that) - include links to important external resources - comments are often read by people who have no idea about the context (this even might just be you in a few years), so make sure to provide context (links, your name, date) - if you are having trouble reading your own code, document it (or better: rewrite it) - only comment as little as possible, as much as necessary - comments become stale and old (code changes, but the comment is not changed with it) -> do not document rapidly changing pieces, only code that has settled - docstring (`/* @param ... */`) for stable APIs - Tests can be documentation: a working example of how to use the API - Leave a (3-5 line) summary of what a module does at the top of it. This is much better in most cases than line-by-line or function-by-function comments - From comments on video [DON'T Comment Your Code (youtube.com)](https://www.youtube.com/watch?v=uHh26-cHU-k): comments should - identify dependencies that are not apparent - describe reasoning for architectural choices - significantly reduce surprise
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);
I don't particularly like the style of comments in the Doom3 Codebase (which is hailed as a very clean and well documented large codebase). There are good bits in there, but also stuff that I find superfluous (not to mention the - probably auto-generated - codeblocks above each function that mostly just contain the function name again)