Personal Recommendations

Comments have caused bitter dispute in the programming world since the day they were invented if not before. Novice programmers are at fault for "commenting everything" and making code nearly impossible to read, or worse leaving outdated or conflicting comments to confuse and distract future maintainers. Experienced programmers are at fault for over-reacting and claiming that no comments whatsoever is the answer, or that they are too busy, presumably because they spend so much time and effort trying to comprehend source code that is not properly commented.

Perhaps the wisest words I have ever read on this matter are "barely adequate is actually spot on".

My personal recommendations are as follows. Take these with a pinch of salt, I do not always practice what I preach, feel free to disagree, etc.

Overview and Navigation. The primary purpose of comments is to guide future maintainers. Every source file should begin with a brief summary of what it contains (nope, it ain’t in this file either mate). As an example, builtins/VM/pJcc.e has "implements :%opJcc and :%opJccE" at the start (plus a bit more waffle, which I concede is an optional personal choice). Yes, really - such trivial one-liners can save an absolute shed-load of time, as long as you can actually trust them. Longer sections should also contain periodic (about every 30 lines/when practical) short bullet-point style notes, ideally allowing large blocks of code to be skipped at up to fifty times quicker than would be possible without them.

When, how, and why. For each (significant, global) routine explain what the parameters are and what gets returned, and ideally show examples. You have heard of this "abstraction" business, right? Or do I really have to read every single line of the actual code to figure these things out? I should also add that I don’t personally subscribe to the "makedoc" school of commenting - it may be better than nothing, but the chances of creating quality documentation as a by-product of coding are slim to quite negative - and if not properly reviewed it may in fact prove worse than nothing, perhaps even forcing difficult enhancements to be made to the original code in order to bring it in line with some misleading documentation that everyone has been following.

Data. If you need four indexes, you probably need four comments, perhaps with the exception of trivial loop counters. Often if you can form a clear mental image of what data has to be manipulated, or indeed precisely what the local or temporary variables a routine requires are for, you barely need to look at the code. A simple example value can make something instantly ping into absolute clarity; while "string filename" has obvious meaning, it immediately asks all sorts of questions that "-- eg "C:\Program Files (x86)\Phix\docs\phix\src\comments.htm"" easily answers. However, take care to use vertical whitespace to separate code and comments so future readers can focus on what they need to. Also take a look at pglobals.e. Pretty much the only reason I ever go anywhere near that file is to read the comments, which I very often do, and I’d be completely lost if it was just a stark minimal list of identifiers.

Temporary stuff should always be clearly marked, and easy to search for. I tend to use "DEV" (we eventually realised that initials, especially of ex-staff, were really not very helpful, and often needlessly disruptive).

Tried that, didn’t work. If you spend four hours trying to fix something, then two days later you have to back out those changes, or you realise this is the N’th time you’ve tried something, then clearly a permanent comment is warranted.

Technical. Difficult concepts need explaining in detail. When you find a dirt-simple solution to a seemingly difficult problem, it can be extremely helpful to show why it is adequate. I often write extremely verbose comments as part of the design process. The formal design should ideally be completely separate from finished code, but whether that is in the source file or a separate file is a matter of personal choice, however the two deadly sins are interspersing design and source code in the same file, or having a source file follow a separate design with no mention of where it can be found. You may not like the design notes for priorities(..optsets) being in psym.e, but it is unfair to claim they make it any harder to read the actual code.

Always consider the (impossible to measure) value of comments: they cost time, effort, and money, and something is terribly wrong if they are not saving twice that. I am acutely aware that I over-comment things by as much as a factor of 10, please do not copy my style! If it has taken you 10 minutes (or 10 hours) to figure out why something is written that way, or indeed dream up some novel approach, slap in a quick note that may save that time when you or someone else is looking at this same code in six months time. Aim for small effort and big savings, but if all you can be bothered with is some terse, cryptic, and inadequate remark that will never help anyone, fair enough, forget it.

You should never reiterate what the code is actually doing in excruciating detail. The "-- add 1 to index" class of comments are (imo) the main cause of anguish. If something is not clear, maybe your variables are poorly named or you are trying to achieve too much in a single statement. Exceptions to this ("actually doing") rule include assembly language, where for example "mov [esi+4],ecx" clearly deserves something like "-- next.prev := this.prev", or what you are doing is sufficiently unusual that the reader has most likely never encountered anything similar before, or perhaps just to confirm that you really are trying to do exactly what it looks like you are trying to do.

One thing that always strikes me as odd is that most people seem to think that comments describe what the program does, rather than what it should do. If the original programmer said "this is what I meant it to do", then when it does anything else, it is a bug. However should that "bug" turn out to be an outdated comment, expect the appropriate backlash. Which leads to the natural conclusion: Never write more comments than you can comfortably keep up to date.

Replicated from someone’s blog (who was apparently replicating someone else’s blog):
In Mike Gunderloy’s In Praise of the Lowly Comment article, he identified 4 types of comments that can serve as our guideline. These 4 types of comments are:
  1. Placeholder comments
  2. Summary comments
  3. Intent comments
  4. Rocket Science comments

Placeholder comments

Placeholder comments are comments that help remind you of some tasks that need to be done some time in the future. The TODO comment is an example of this type of comment.

Summary comments

Summary comments are comments that help explain what a chunk of code does. This type of comment helps explain a block of code at a glance. This prevents the need to read every line of code in the program.

Intent comments

Intent comments are comments that help explain why a class or method is there. For example, you might want to explain why you needed to extend from the DownloadClass instead of the ProjectClass.

Rocket Science comments

Rocket Science comments are like tutorials that help explain the intricacies of a very complex algorithm. References to the algorithms used may also be included in this type of comment.

The lesson here? To improve code clarity, use comments judiciously.


Finally, a small collection of examples:

While arguably/theoretically easier to maintain, there is no real difference between
    constant SIGCHLD = 17
        ...
        pid = SIGCHLD
(ie no comments, the identifier alone is enough) and
        pid = 17    -- SIGCHLD
(admittedly multiple uses of that constant would increase the chances of an undetected typo), however:
        pid = 17
is in stark contrast suddenly truly awful: it will take far longer to read and understand once than any savings made while writing it.


-- 
-- Dear maintainer:
-- 
-- Once you are done trying to 'optimize' this routine,
-- and have realized what a terrible mistake that was,
-- please increment the following counter as a warning
-- to the next guy:
-- 
-- total_hours_wasted_here = 42
-- 

-- If this code works, it was written by Paul DiLascia. If not, I don't know who wrote it