Hacker News Reader

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

> Do not leave any other types of comments! Ever! Not even method docs.

Have you ever looked at a very large project(blue whale as I'd like to call them)? In 10 years time, 90% of the people who have worked on it initially will be gone from the company (or stopped contributing if it's an open source project). You are making everyone else's life a nightmare. To my mind the one project that got it bang on is postgres. It is by no means a library and the community's approach is perfect. Open up any of the source code files at random and you'll see what I'm on about. Just scrolling through the code and comments once will be enough for you to figure out exactly what is there and why.

> Have you ever looked at a very large project

> You are making everyone else's life a nightmare.

I work on code touched by tens of thousands of other engineers. In my experience, code without comments is typically structured, easy to read, and does exactly what is written. Code painted top to bottom with comments tends to be muddied, confusing, and more junior in nature.

The shape of solutions is common. You're not reinventing the wheel with every new project. Engineers are familiar with the design patterns, frameworks, and algorithms you use, so you don't need to force a context switch to point them out.

You can use the symbols themselves as a form of documentation. Instead of having an entire algorithm inline, individual queries or processing steps might be put into their own self-documenting methods:

    verifyMarkdown(article_rating: &Rating)
    upsertRating(article_rating: &Rating, author: &User, transaction: &Transactor)
    publish(article_rating: &Rating, transaction: &Transactor)
    enqueueSubscriberNotifications(author: &User)

Small pieces of code might not require a functions to wrap them, but by naming small units of behavior, you can communicate your algorithm step by step without comments.

This is only one type of communication technique you can use. There are bountiful ways to improve your clarity.

I apologize if my examples are obtuse. It's late.

OK, good points, but my argument stands in most cases: It doesn't matter how experienced a developer is. You'll rarely see anyone as pedantic as I am when it comes to conventions, structure or organization, but there have been multiple instances when I've had to cut corners to meet some deadline. I work on an enormous projects with few developers. Say we all decide to go full Eric Cartman tomorrow and call it quits. Guess how long it's going to take someone else to work their way through 8 years of development without a single comment? My bet - they would keep hitting rocks day in and day out.

In the case of thousands, the likelihood of everyone leaving at the same time is much lower, but I'll go back to my postgres example, which I genuinely use as a benchmark as far as code goes. If everyone abandons it today for some reason, everything is so well thought out, well structured and documented that new people can jump in right away and the development won't be slowed down dramatically, granted that the new developers follow the current process.

> Have you ever looked at a very large project(blue whale as I'd like to call them)?

Yes, I have. And almost none of the comments matched the code. My new "head of engineering" ruled that almost all lines of code must have matching comments. I now frequently find people changing the code but not the comments during code review.

Well that's an organizational problem. Personally when I do code review and I see a comment which is redundant or doesn't match the code, I immediately return the PR and tell the developer to fix it.

- Comments aren't executed or covered by a test suite so it's much easier for mistakes in them to slip by. A comment like "Close the file when..." when it should say "Open the file when..." could easily slip by review or when the underlying code changes. Same with typos and wrong names.

- When you're adapting existing code, misleadingly named variable names and function names are going to be quickly noticed and fixed as developers are forced to read them (unlike reams of external docs or big comments). If you name a function "close" instead of "open" by accident, someone is going to notice fast.

> Well that's an organizational problem. Personally when I do code review and I see a comment which is redundant or doesn't match the code, I immediately return the PR and tell the developer to fix it.

You can justify any misguided developer practice like this though. The question is "is this a worthwhile thing to spend time enforcing?" and not "is it possible to enforce?". Getting rid of manual checks is a good thing when you can too.

Things slip through inevitably but it's easy to correct them when you spot them eventually or am I missing something? That's what I do and that's what we've agreed upon with all developers and it's working flawlessly.

This is turning into a philosophical question rather than a development one. What is worthwhile to begin with? As per Maslow's pyramid it's breathing, eating and drinking. I've had this argument with a former co-worker who was strictly against writing documentation and comments, precisely because it wasn't "worthwhile" and a "waste of time". "Right... Got anywhere to be right now or is your plan to finish your task till 11 and spend the rest of the day scrolling through facebook?" Common occurrence for that guy as a matter of fact. We've fought for years to take out the "we need that eod" to transition to long enough periods with realistic deadlines and plenty of time to spare for tests, documentation and so on. And it is something that we have now. It is proprietary software but the postgres example is perfectly valid - simply look at it.

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

Yes! And even then:

    const int maxSampleRateForMultiSpeakerModel = 22000
    source = downsample(source, maxSampleRateForMultiSpeakerModel);

Absolutely! Hoist parameters up so you can make commentary on them.

Or maxMultiSpeakerSampleRate since one of the lessons from the article is that good variable and function names remove the necessity for comments. Naming things, unfortunately, is hard.

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.

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.