My mission to (almost) eliminate code comments

Actually, there are many cases for wich I believe the comments are useful:<p>- When you have some &quot;complex&quot; technical code. Using natural language is sometimes the most effective way to explain what is done by the related code.<p>- When you deal with some business logic that can become weird an 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&#x27;s always useful to have some background explaining why the code has been written in such way.<p>- When you have to consider history on a large code base. I know that people on HN mostly work on new shiny projects, but with legacy applications, you have to deal with all the bad&#x2F;incorrect choices that were made before, and refactoring is not straightforward and is costly. I&#x27;m not saying it should not be done, but sometimes, you can work on it only in an incremental way. Comments allow you to add some perspective on the code (explaining the reverse engineering you&#x27;ve done, the initial assumptions, why they turned out to be incorrect, what should be done to improve the situation, etc).<p>Also, I disagree with the facts that comments are born out lazyness. &quot;Lazy&quot; developers don&#x27;t bother writing comments. Actually, there don&#x27;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&#x27;ve seen from such people are &quot;commented code&quot;, because &quot;it might be useful&quot; (it never does).<p>I see comments as a way to engage a (one way) conversation and provide useful and meaningful information to a future code maintainer. Sure, such comments should not clutter the code, be relevant and meaningful, stay up-to-date but it&#x27;s - as many other things - a skill that require time to get it right.<p>Looking to eliminate all of those is not an approach that I think should be followed (but it&#x27;s just my opinion). Focusing on allowing the code to be understandable by an hypothetical maintainer in the future is more relevant. If extra comments have to be added, so be it. These are tools, not ends.

I have mixed feelings about this. I think it depends on the project you are working on. If your codebase can be packed into a few hundred lines of code, with nothing fancy or complicated and no code is being injected from elsewhere, then the author is absolutely right. 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. However if your codebase is composed of several million lines of code(like a lot of the ones I work on), things change. Using readable names is a perfect general advice but eventually you end up with complex logic, which is not necessarily the result of some developer who just wanted to get a task out of their way but could be as well a result of &quot;business needs this by Monday, 3 weeks ago&quot; or simply some mind boggling edge case which needs to be handled. In which case, adding some inline comment with an explanation as to why something is there and ideally a link to your ticketing system can be a life savior. I&#x27;m far not a fan of things like:<p>&#x2F;&#x2F; Increment counter by 1.<p>counter++;<p>You should never do that unless you are studying programming and you have been required to explain every line of code along the way(though I don&#x27;t know why a professor would ever want that, certainly no one ever asked me to do stuff like that).

Urg, I strongly disagree with this take. First, comment your damn code if you work with others so that they don’t waste time reverse engineering your code. Sure use better variable and function names but do not create a function that can be inlined just to replace a comment... You’re adding abstraction and making your code less clear (which is not what you intended).

Pretty much the opposite advice than <a href="http:&#x2F;&#x2F;number-none.com&#x2F;blow&#x2F;john_carmack_on_inlined_code.html" rel="nofollow">http:&#x2F;&#x2F;number-none.com&#x2F;blow&#x2F;john_carmack_on_inlined_code.htm...</a>

Just my 2c:<p>- the theme is to move the comments in the code by using variable names and function names that tell a story. Not a bad idea by itself, but nothing special there either.<p>- moving a simple one-liner arithmetic operation to a function that is stored somewhere else is a complexity increase that is hard to justify. Every line of code can be hidden behind a function, is that productive, acceptable and lean?<p>- not trying to be picky, but for free shipping I would prefer to do shippingCharge = 0 instead of that because that is what you want to do.<p>And a question: if the comments are out of the code (where they are mostly contextual), what kind of documentation is left behind for the support team? In my world the support team has encounters with code written 10 years ago by people no longer around, they know high-level what the code is doing, but the devil (bugs) is in the details.

How strange - I&#x27;ve always found comments useful. As I&#x27;m not a developer but sometimes have to edit different files in the code just to enable&#x2F;add in new parameters (so engineering resource isn&#x27;t needed to be planned in), it&#x27;s always been helpful to have explicit guidance in the code as to what I&#x27;m reading is doing. Still get a code review afterwards anyway, but minimises risk.<p>If you&#x27;re expecting non-developers to sometimes interact with your code or to help with troubleshooting, in-line comments will always be appreciated.

To give some &#x27;yes, that&#x27;s maybe great, but is it practical?&#x27; feedback; I often work with (bigger) companies where code reviews fail if you don&#x27;t have:<p>- comments, the more the better - design patterns, the more the better<p>Even if absolutely useless; the over-architecting just for over-architecting sake is quite... Not only does it take a lot of time to actually reuse the code (a lot&#x2F;all of those patterns are conceived for reusing code in the first place but in reality it takes people a long time to get into them and the gains are not convincing aka I see people just plonking together a little microservice in a fraction of the time with Node and (virtually) no design patterns to replace (parts of) the java&#x2F;c# monster that does the same thing just to make the deadline or to skip diving into the sea of blackness), but the comments really do not help at all; they are just there to have comments. And the design patterns (+ the way they are used) are considered standard (they are, but not for young people who have no degree and no experience applying them, or maybe even knowing they exist).<p>Still, without all that, the merge requests are being declined until you pop in random drivel &#x27;for best practice&#x27;.<p>I am a fan of terse but readable code these days (it changes somewhat); the design patterns are more and time wasting (to me), especially when enforced in this way (but I think everyone will agree with that anyway).

This isn&#x27;t a good idea. And his functions, well... they&#x27;re gross. You&#x27;re going to replace<p><pre><code> orderCost = orderCost - shipping; </code></pre> with<p><pre><code> ApplyFreeShipping(); </code></pre> Now you&#x27;ve violated referential transparency, introduced some unnecessary global and mutable state, and not really made anything clearer.<p>Let&#x27;s take his other example:<p><pre><code> var outstanding = GetOutstandingOrders(); </code></pre> Into<p><pre><code> var allOutstandingOrders = GetOutstandingOrders(); </code></pre> Please for the love of god, no. 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&#x27;s a common tenant among APL&#x2F;J&#x2F;K programmers as well.<p>Here&#x27;s how I wish programs were structured:<p>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). 2) Make your variable names abbrevations or acronyms, like instead of &#x27;convertInt&#x27;, call it &#x27;ci&#x27;. 3) Comment every function and keep each function to only a couple lines. 4) Because your functions are so small and dense, you&#x27;ll never need to modify them, only throw them away. 5) Bam, your comments and never out of date because the functions you&#x27;re writing never need to be modified, only deleted.<p>Unfortunately, most programming languages don&#x27;t give you sufficient power to do anything in a couple lines. Which brings up the question, why don&#x27;t we switch to those that do? Honestly, J or K would be totally usable for the vast majority of programming problems.

&gt; The majority of comments I write are a born out of lazy coding<p>Then you&#x27;re doing it wrong. Comments can be used to describe your thinking process, an algorithm, or explain esoteric code. I write comments with the target audience being people who inherit my code 5 years after I&#x27;ve left the project.<p>I&#x27;d argue that lack of comments on large projects may be an indication of an immature developer.

Concerning the example with the outstanding orders, I think the main problem in practice is not so much the poor naming of the variable, but the lack of documentation of the called function (&quot;Process&quot; in this case). I could live with the variable name &quot;outstanding&quot;, but the IDE should better show me a good explanation of what the function &quot;Process&quot; is doing when I point with my mouse on it.<p>The example is also a good example why type declarations are so helpful. Just by looking at the lines &quot;var outstanding = GetOutstandingOrders()&quot; or &quot;var allOutstandingOrders = GetOutstandingOrders()&quot;, I could not tell whether the function is returning a list of outstanding orders or whether it has a side effect (reading the outstanding orders into a buffer) and returning a boolean indicating that there are outstanding orders.

Every programmer comes to believe that comments are the symptoms of bad code at some point in their development. Many, but not all, of them realize that they are wrong quite quickly afterwards.<p>Comments aren&#x27;t a crutch to be used because of an impairment , they are helpful support in the face of the challenges of diverse technologies, poor documentation and difficult communication over time and space. Importantly they are integrated into the code base and are aimed at a very specific consumer - future programmers. Future programmers who may include you!

I worked in a place where if you commented your code you would fail the code-review.<p>I had a mate who worked at a place where the code once it was checked in was ran through a processor that deleted comments!

To counter the negativity, this was a good post and I agree with it.<p>The example with the unneeded comments for conditionals and the one that explains &quot;what&quot; a function does is something I see even senior devs do all the time.<p>I think a lot of replies here aren&#x27;t reading the article or are focusing on nitpicky examples.<p>&quot;Comment your code!&quot; is a deeply ingrained piece of advice people throw around without the warning that a lot of coders write comments in place of good function names and variable names.

A useful way to think about it is that <i>names are basically comments, but only names can be looked up by an IDE.</i> When looking for a frobnicator I can find it trivially if there is something <i>named</i> &quot;frobnicator&quot; or anything similar. If there is a <i>docstring</i> mentioning frobnication (maybe with some &quot;alternative&quot; spelling or other word form like a verb when I&#x27;m looking for the noun), on the other hand, that&#x27;s <i>much</i> harder to find. And once I find it, I still have to locate the <i>actual frobnicator somewhere near the comment.</i> Even this is the ideal case, where only one comment mentions frobnication. What if it&#x27;s a common word? Now the chance of finding the right thing in a reasonable time goes <i>way</i> down if it&#x27;s not named properly.

The author has a point that comments may be superfluous when going through a code line by line.<p>However, that&#x27;s not the only sort of code-reading. Comments can sometimes be better to get an overview of a complex program. Not if it is your own code, sure, or even in a code-base you work in. But faced with a huge amount of foreign code, over-commenting can be very useful (at least for me).<p>This should not be an excuse to write bad code - here I agree with the author. But given that, I see little downside in good comments.<p>It&#x27;s an extremely challenging task to think about how others would perceive our coding. Perhaps the reader isn&#x27;t familiar with a technique or function that seems obvious to you? It&#x27;s the same as trying to give a lecture on a subject. Pedagogically, it&#x27;s preferable to have more comments than less.

This is the approach advocated for in <a href="https:&#x2F;&#x2F;www.goodreads.com&#x2F;book&#x2F;show&#x2F;3735293-clean-code" rel="nofollow">https:&#x2F;&#x2F;www.goodreads.com&#x2F;book&#x2F;show&#x2F;3735293-clean-code</a> .<p>I like it, but I know some language communities don&#x27;t.

I&#x27;m not so sure about converting<p><pre><code> if (customersFirstOrder) { &#x2F;&#x2F; Apply free shipping orderCost = orderCost - shipping; } </code></pre> to<p><pre><code> if (customersFirstOrder) { ApplyFreeShipping(); } </code></pre> Does `ApplyFreeShipping` work on global state? How do we test it? At the very least it should be something like:<p><pre><code> orderCost = ApplyFreeShipping(orderCost, shipping); </code></pre> which has advantages over the first version but is not necessarily better. The suggested version is just awful though.

Terse variable names are easier to read if you&#x27;re doing anything non trivial. I only need to understand what it is once, not every time the symbol appears. If the abbreviation isn&#x27;t clear then add a comment when it&#x27;s declared. The comment is just as likely to go out of date as the variable name itself so there is no cost to the comment.

If you don&#x27;t like to see the comments hide them in your IDE. Most decent IDES let you set the background and foreground colours based on the code.<p>i.e. I have comments for type &#x2F;* *&#x2F; and &#x2F;&#x2F; set to be grey on a slighgly darker grey so they are pretty much hidden (as they are useless most of the time).

After seeing Damian Conway‘s training courses teach this, I’ve tried to shoot for this style ever since.<p>It definitely lowers cognitive load and “feels” better, but I still feel bad when adding function call overhead just for style (maybe the compiler is actually that smart and there’s no hit)

<p><pre><code> orderCost = orderCost - shipping; &#x2F;&#x2F; Apply free shipping </code></pre> Now it explains why.

Related article (published in 2017):<p><a href="https:&#x2F;&#x2F;testing.googleblog.com&#x2F;2017&#x2F;07&#x2F;code-health-to-comment-or-not-to-comment.html" rel="nofollow">https:&#x2F;&#x2F;testing.googleblog.com&#x2F;2017&#x2F;07&#x2F;code-health-to-commen...</a>

I like how the code in (almost) all the examples can lead to horrible side-effects.

Does this include doc blocks? I mean a lot of ide&#x27;s have addon info they glean from those, as well as some api-generators use annotations to generate them, and same w&#x2F; phpunit.

There I was all ready to get my pitchfork out and then I read the article and damn! These are good points!

Comments are great for teams and your future self but your point is well taken

i like the idea in general but the example is quite awful.