Great analysis of comment types. I tend to do all the first six, including the guide comments. I can't understand people who think code should be completely sel

Great analysis of comment types. I tend to do all the first six, including the guide comments. I can't understand people who think code should be completely self-documenting. There's always so many edge cases. Are they seriously never puzzled by past code they wrote? Every time I go back to any projects I haven't touched in a couple of months I'm always a little disoriented, and it was all code I wrote! The fewer comments I wrote usually the more I regret it later. Guide comments in particular just make it so much easier to find my place again. And I'd go as far as to say they're almost mandatory for any math related code with a lot of complicated conditions. It's 100x easier just reading the guide comments. Not that they should repeat the if statement exactly, that's pointless. But describing what's happening (the bigger picture that is) really helps imo, and adding an example is even better. I try to keep them short though, single sentence, usually 1 comment for every 5-10 lines depending on the complexity of the code. For example, I was writing a sort of panel/window manager, it had a ton of conditions that looked like: if (area_left < current_left) {/*...*/} if (area_right > current_left && area_right < current_right) {/*...*/} You could probably figure out what was going on if you saw it was inside the resize handler for a panel (current_*) and looping through all the other panels/areas, but something like "// finds any areas that will limit our movement" right above the ~10 line section is so much easier to understand. For more complex situations I might have added a visual description as well: "// e.g. given panels [1][2][3] - when dragging a side of #2, find any limiting panels to the right (#3) and left (#1)", though usually I keep the examples to function comments. I'm torn about debt comments though, especially for protoypes/beta projects where they're the most common. On the one hand, if they're in the code, it makes finding where changes for certain features should be added easier if you add them consistently. On the other hand, it's then hard to see an overview of them all. Putting them in their own file makes it easier to manage them and helps me remember what I was working on, but then I have to go hunt down all the places the functionality needs to be added to. Maybe some combination would be better. Like naming them something specific: "todo - feature - somefeature" then having the details of somefeature in the todo file. Or another solution might be to use headers as someone else has described, then refer to the filename/headername/s that need to be looked at in the todo list. Usually imo, the more comments the better, so long as none of them are outdated (working alone though I haven't really found this to be a problem). You can always remove comments, it's much harder to add them in months after you wrote some code.