8.4 Writing Good Comments

Comments are a lifeline for programmers trying to understand tricky code. In general, the less obvious it is what you are doing, the more you need a comment, and the more detailed it needs to be. You should always be on guard when you’re writing code for stuff that’s tricky, and should constantly be putting yourself in someone else’s shoes and asking if that person could figure out without much difficulty what’s going on. (Assume they are a competent programmer who understands the essentials of how the SXEmacs code is structured but doesn’t know much about the module you’re working on or any algorithms you’re using.) If you’re not sure whether they would be able to, add a comment. Always err on the side of more comments, rather than less.

Generally, when making comments, there is no need to attribute them with your name or initials. This especially goes for small, easy-to-understand, non-opinionated ones. Also, comments indicating where, when, and by whom a file was changed are strongly discouraged, and in general will be removed as they are discovered. This is exactly what ChangeLogs are there for. However, it can occasionally be useful to mark exactly where (but not when or by whom) changes are made, particularly when making small changes to a file imported from elsewhere. These marks help when later on a newer version of the file is imported and the changes need to be merged. (If everything were always kept in CVS, there would be no need for this. But in practice, this often doesn’t happen, or the CVS repository is later on lost or unavailable to the person doing the update.)

When putting in an explicit opinion in a comment, you should always attribute it with your name, and optionally the date. This also goes for long, complex comments explaining in detail the workings of something – by putting your name there, you make it possible for someone who has questions about how that thing works to determine who wrote the comment so they can write to them. Preferably, use your actual name and not your initials, unless your initials are generally recognized (e.g. ‘jwz’). You can use only your first name if it’s obvious who you are; otherwise, give first and last name. If you’re not a regular contributor, you might consider putting your email address in – it may be in the ChangeLog, but after awhile ChangeLogs have a tendency of disappearing or getting muddled. (E.g. your comment may get copied somewhere else or even into another program, and tracking down the proper ChangeLog may be very difficult.)

If you come across an opinion that is not or no longer valid, or you come across any comment that no longer applies but you want to keep it around, enclose it in ‘[[ ’ and ‘ ]]’ marks and add a comment afterwards explaining why the preceding comment is no longer valid. Put your name on this comment, as explained above.

Just as comments are a lifeline to programmers, incorrect comments are death. If you come across an incorrect comment, immediately correct it or flag it as incorrect, as described in the previous paragraph. Whenever you work on a section of code, always make sure to update any comments to be correct – or, at the very least, flag them as incorrect.

To indicate a "todo" or other problem, use four pound signs – i.e. ‘####’.