My mission to (almost) eliminate code comments

> When you have some "complex" technical code. Using natural language is sometimes the most effective way to explain what is done by the related code.

Totally agreed here. There's some code in underscore that recursively copies strings as a way of writing '' because it happens to be fast. You'd think it was really weird if it wasn't marked as a performance optimisation.

> When you deal with some business logic that can become weird at one point (process all these things in some ways, excepts these ones, weird edge cases, etc.). From a developer perspective, it does not always make sense, but it's always useful to have some background explaining why the code has been written in such way.

That's the 'why' addressed explicitly in the article.

> Also, I disagree with the facts that comments are born out lazyness. "Lazy" developers don't bother writing comments. Actually, there don't care, and most of them do not even realise that at some point in time, someone will have to browse, read and understand their code.

> The only kind of comments I've seen from such people are "commented code", because "it might be useful" (it never does).

It sounds like you largely agree with the article. Save comments for 'why', you want to eliminate meaningless comments.

I think your point is in line with the article. Comment WHY you are doing something, rather than commenting HOW. And, if you are in a hurry and the logic/naming is somewhat unclear, leave a comment to clarify. In a future refactor, the logic might be made more clear and comments removed.

I agree entirely.

As far as code that handles bizarre edge-cases, I tried to cover that in "Comments that explain why". Perhaps I missed the mark a little, but I think I was intending to agree with the point you made.

"Often, it’s because I’ve profiled it and found it to be significantly faster, or because it catches an edge-case that a more intuitive method of doing the same thing might not .. Comments like this get to stay."

To your point about "business needs this by Monday, 3 weeks ago". Under those circumstances, I write comments to explain my rushed code all the time.

In my personal case though, I'd consider this to be "Comments as an excuse not to refactor". It might be a good excuse (maybe the business need trumps readability in the short-term), but I know it's still an excuse and not something I should be doing all the time. I'm trying to get better at going back and refactoring those things later.

> Documenting what a function or a method does should be sufficient and imo you should do that in all cases, just for the sake of making it easier for new developers to jump into the project if they prefer using some fancy IDE.

Document nothing until you have to do something weird and unexpected.

An example might be:

    // NB: We're downsampling to 22khz because we found that the 
    // multi-speaker model chokes on higher sample rates.
    source = downsample(source, 22000)

Or:

    // We don't perform internal retries here because our clients 
    // handle that themselves when we respond with a 429. 
    retryCount = 0

Or:

    /* Firefox renders this mistakenly, and overflows the 
       element. We opted to add padding to account for this 
       difference. See BUG-4282 for more details. */
    padding: 0 0 3px;

This strategy captures all of the things that you'll forget, but leaves nothing that might go stale. In essence, only the things of value that couldn't be intuited from the code itself.

Do not leave any other types of comments! Ever! Not even method docs. (The only exception being if you're writing a library and want to generate a documentation website).

You'll find that you start writing code that is like poetry. Structured, naturally intuitive, and easy for others to read. You'll become a better programmer, and your code base will improve dramatically. Comments, of course, will never go out of date.

The big take-home point here is that comments may be symptom of the code itself not being as clear as it could be. First priority is to make the code itself clearer, that will eliminate the need for a comment to "make it understandable".

Compilers can inline functions. Functions can be tested, reused and composed. Comments usually rot.

I’m curious if anyone has tried some sort of editor plugin that, instead of doing something like “go to function” when you encounter a call, instead temporarily inlines the code into what you’re reading so you’re not jumping around. Seems like this might be the best of both worlds, with abstractions hidden but instantly available to scrutinize when necessary?

Blog post author here.

I'm certainly not qualified to disagree with John Carmack! I can speak for my own experience, however.

I understand the argument that moving small sections of code into methods/functions hides the details. However, I probably spend more time reading code than writing it. When I'm in 'reading mode', I really just want to understand the control flow; I want the details to be hidden from me.

If I'm debugging code, or looking for performance improvements, then I do need to see that complexity. More function/method calls will make this slightly harder for me, but it's a trade-off I'm willing to make for the more common case, I think.

Well, John Carmack is in game programming. That is quite a different field where performance is of supreme importance. I might imagine that things are different there, although I cannot claim to know because I do not work in game programming. For 'normal' programming where performance is not the thing one should primarily be worrying about the OP is correct. He is also not the first one to make this observation. E.g., many years ago I read https://blogs.agilefaqs.com/2009/08/19/are-comments-evil/ . What is written in the OP really should be common knowledge with the provision that perhaps it might not apply in game programming.

I believe that John Carmack's argument considers both the semantics of code and reality of programming languages (here, C/C++), while the OP only considers the former. Ideally naming things without any additional problem (for example, as others noted, extracting a block of code into the global scope violates referential transparency) should be easy, but many languages don't. Carmack is using a comment as a means to give a name without introducing unwanted abstractions.

I agree entirely that this isn't anything new, I hope I didn't imply it was. This is simply my own reflection on how to improve my coding style.

> "Every line of code can be hidden behind a function, is that productive, acceptable and lean?"

I've seen some advocate for that exact thing, but I certainly wouldn't go that far. I don't think we have to have one or the other, there's a middle ground in my opinion.

If the code requires a comment to explain it, then maybe a well-named method/function is a better option. If the code is obvious in its own right (looping over a collection to add 1 to everything, to use a dumb example) then I don't think abstracting it is justified.

I certainly don't have any objection to single-line functions to add readability per-se. (with the caveat that a compiler would produce the same result either way, or otherwise the performance of another function call isn't an concern. I'm talking purely about readability here)

This is a great point. You might take a different approach depending on when you expect your reader to already be proficient in the language or the framework, compared to whether a non-developer might be reading the code.

One argument against these kind of comments is that they aren't the right place to teach somebody a programming language. However I can definitely see cases where they are justified.

I agree that the examples aren't great. I struggled to come up with terse examples to illustrate the point, but I stand by the general premise of the post.

I'm afraid I can't agree with making variable names as short as possible as a general rule, though.

I think that the length of the variable name should be linked to a) how long it lives for and b) the distance between the declaration and the usage.

For example, I'm personally OK with using 'i' for the index in a 'for' loop, but stand by longer names such as 'allOutstandingOrders' for variables that are used throughout a function, where the declaration isn't within a few lines of the usage.

I agree that variables names should be short, but not "as short as possible". They should be as short as possible while remaining unambiguous and avoiding loading short-term memory.

"allOutstandingOrders" does not look to me like a long variable name.

> Make your code as terse and dense as possible

I really hope I never get to work with any code you've written.

> Make your variable names abbrevations or acronyms, like instead of 'convertInt', call it 'ci'

I'm starting to think this comment is satire now.

If I have to read the comments on a function or variable to figure out what it does then my productivity is going to be absolutely kneecapped if I'm a newcomer to your project.

Length (as proxy of expressiveness) of variable name should be a function of the scope of the variable. It there are only a few lines between declaration and last use of a variable a single letter name is often suffcient (i,j,k for loop vars, p, q, r for pointers, l for length, n,m for upper bounds, a,b,c,t, etc. for temporaries. If the scope is over a longer section, without to much repetition it is appropriate to have a longer name. If it is a global variable with external linkage, it is very good to have a descriptive name so that it is also clear what it is when looking from outside.

Heartily disagree. If I see a method/variable named something like "ci", I will reject it in code review.

Descriptive variable and function names make code easier to understand, not harder.

> 1) Make your code as terse and dense as possible so you can see as much of it at one time as possible (see code written by Arthur Whitney).

Why? I don't want to see as much code as possible. I want to see the code I'm interested in. If I can read 4 lines of code and understand what it does, I spend less time and energy than reading 20 lines of code and trying to reverse engineer it.

> 2) Make your variable names abbrevations or acronyms, like instead of 'convertInt', call it 'ci'.

That makes no sense, it's gross and has only drawbacks.

> 3) Comment every function and keep each function to only a couple lines.

So you need one or more comments for two lines of code?

> 4) Because your functions are so small and dense, you'll never need to modify them, only throw them away.

If you're only writing them to throw them away, why not optimize and never write them in the first place?

> 5) Bam, your comments and never out of date because the functions you're writing never need to be modified, only deleted.

This is sarcasm, right? I feel like I've been trolled.

Perhaps we need smart refactoring for our identifier names that remove redundant words (eg “all”) and replace long words with shorter synonyms (eg pending vs outstanding).

   var pendingOrders = getPendingOrders()

I appreciate the idea of density allowing you to "see" the bigger picture better. It's something I value too. But ideally you can find a balance between the best of both worlds.

Why in the world would you comment every function if you could just embed the comment into the code?

    x@>#:'x       sort order alphabetically in place

does not to me seem substantially different from

    order = alphaSort(order)

When the comment is embedded into the function, the same effect you described (~"because your functions are small, you can throw your comments away with the function "). These variable and function names need not stick around any more than K comments. Ideally, the name only exists for as long as it has utility, and if it has no utility, it is an anonymous function / never stored in a variable. If there is marginal utility in the name, then sure, use a single character placeholder `o=>sort(compareFn)`. As soon as you need to hold onto an idea of a noun (as in a larger mutating reference frame) or a verb (as in any function you want to both compose and reuse), then names become helpful handles for reasoning about the code over time and opportunities for reuse, `alphaSort=sort(alphaCompareFn); sortedOrders=alphaSort(rawOrders)`. If there's no opportunity for reuse or if the function is trivial, THEN eliminate the longer names.

The harder part here is the middle area. With very concise code, you can see the whole thing, but with sufficient complexity, you may not be able to hold what "o" is at any given time in your head. With verbose code, the code will read like highly precise English and you are unlikely to be confused about what "alphaSortedOrders" means, but you might lose track of what the larger program is doing.

The real problems arise in the middle: is "orders" my sorted or unsorted orders? If it's not concise enough, you can't immediately see it, and if it's not verbose enough, you don't have a handle on what it is you are operating on.

---

Verbose code helps for transferomg "comments" across code boundaries, as when looking at the function signature when calling a function. I don't see how this is substantively longer than doing the same thing with a comment, and it provides additional utility for contextualizing chunks of code. When you change the "job" of the code, you change the variable name at the same time.

So while within some complex and mutating function you might want "rawSortedOrders", in some other context where you already know what you have, you strive for density.

    finalizedOrders = rawSortedOrders.map(
      o=>o.id=guid()
    )

or

    finalizedOrders = rawOrders.pipe(
      sort(localeCompare),
      map(o=>o.id=guid())
    )

> Variable names should be short, and in my controversial opinion, as short as possible. Long variable names actually make code more difficult to understand, not easier. Rob Pike talks about it in the Practice of Programming, and it's a common tenant among APL/J/K programmers as well.

https://en.wikipedia.org/wiki/Argument_from_authority

But as short as possible doesn't mean:

> Make your variable names abbrevations or acronyms, like instead of 'convertInt', call it 'ci'.

'ci' has no meaning. It is not a possible name for 'convertInt' because 'ci' is not a name. I have to visit the function to determine what 'ci'-ing something does. In 'ci', in turn, I'll have to deal with more minified code.

I couldn't disagree more about variable name length, unless you're writing complex math where a variable is referenced a dozen times in one function.

Specifically in this case it was:

  if (customersFirstOrder) {
    ApplyFreeShipping();
  }

when really the `if` should be inside ApplyFreeShipping as it is part of its rules: when and how. We just 'enable' free shipping as it applies.

Variable naming is secondary here.

Why isn't this the body of a `ProcessOutstandingOrders` method?

  var outstanding = GetOutstandingOrders();
  ...
  Process(outstanding);

> Then you're doing it wrong.

I... I think he knows that. I don't think he was ever going to say "The majority of comments I write are born out of lazy coding, so that's perfect."

I'd say that's doing it right. There are typically more effective ways of documenting code - i.e. better abstractions, naming and tests. The problem is that they are more expensive than comments. Comments are cheap and often better than nothing.

Wow! I'm not sure I'd go as far as to eliminate comments entirely!

My aim is just to write _less_ comments, so the ones I do write mean something and aren't just noise.

IMHO this is the worst of both worlds. Comments very easily get out of sync with the code then.

I prefer the comments to stand out more than the code. Also helps eliminating useless filler comments since they are so noticeable. If you have comments, they should be important and helpful.

I don't think this really makes much sense. In my experience people who heavily comment their code don't put much effort into making the code itself all that readable. People who eschew comments are more likely to focus on writing self-documenting code. (Yes, there are people in both camps that go the other way, but I find those less common.) Hiding the comments will just make the difficult-to-read code harder to understand, and will make it more likely that changes to the code will ignore the comments, and they'll become out of date.

The author addresses this in the article.

Only if your function has side effects that the name doesn’t imply.