# 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. That said, diligently refactoring your code into something so elegant and lucid that it genuinely needs no comments, is a very fine goal indeed, though for my money it is somewhat rather exceptionally rare that a few simple "eg xxx" don’t help.
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 tough problem, it can be extremely helpful to show why it is adequate. I often write extremely verbose comments as part of the design process. Some say the formal design should be completely separate from finished code, and that it is a cardinal sin to intersperse design and source code in the same file, but I say that is nowhere near as awful as realising some code is following what is a probably rather helpful external design document, but with no mention whatsoever of where it might 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, and I’d challenge just about anyone to comprehend a comment-free copy of that 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 and quite rarely just to confirm that you really are trying to do exactly what it looks like you are trying to do.
You should also never use a comment instead of a better variable name. It is quite simply utterly ridiculous to write "integer b -- bitmask" when "integer bitmask" is just all-round-better, and if you’re needing single-char names to get the code to fit on the screen, then you’ve got bigger problems than comments, and further it’s not really very likely they could ever help or improve that kind of code. Note that you can still have some pretty decent acronyms that deserve expanding, such as "sequence plank -- pete lomax’s awesome nostalgia kicks", as long as you don’t overdo the frivolity or need to remember 37 such things to comprehend the code.
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.
With that in mind, always try to eliminate comments, simply by making them completely unnecessary, for instance replace

        j += 1  -- increase padding

with

        padding += 1

Obviously things are not always quite that easy, and "eliminate deadwood" is very different to "be not helpful".
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 such inline literals increase the chances of an undetected typo), however:

            pid = 17

is in stark contrast suddenly truly awful: it will take hundreds if not thousands of times longer to read and understand just once, even if you’re good with google, and you’re even making that harder for yourself, than any savings made while writing it (assuming you knew what it meant in the first place).

        sort(users) // sort the list
        sort(users) // show new users on top

One of those comments adds nothing but pointless irritation and annoyance, the other explains why.

    --
    -- 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

    -- Good programmers don't comment their code. It was hard to write, should be hard to read.