[flatline]

It really depends on the comments. Best practice is to comment “why” something was done, not “what” is being done, or “how”. Every programmer can read code, most code should be pretty self-explanatory. But in any sufficiently complex routine, there are going to be some things that a programmer struggled to get working the first time, that they had to work around, or that was simply unintuitive. These should be commented. Generally I’ve found uncommented code bases to be thrown together haphazardly and to be of lower quality. Same with those that only trivially leave comment breadcrumbs about what is being done, duplicating the code itself.

[bravetraveler]

"Why" is a really good way to put it, like you say - doing "What" just repeats something a novice, possibly even a layman, could distinguish.

I tend to treat them like a strange hybrid of a story with editor's notes.

Here's where we're going... but oh no! Something is in the way. We need this critical, but painful to acquire shovel.

If I anticipate even the slightest bit of refactoring around it, I'm noting what devilishness lead me down this path.

TLDR: anything that could be abstracted away/not exist, probably deserves comments on why it does... perhaps even how it could be removed.

[slily]

It depends on the domain. I would be cautious about assuming that concise comments explaining what is being done in a block of non-trivial code are unnecessary. I have seen too many people write code they assume to be trivial (after spending days/weeks/months/years developing necessary background knowledge to understand it) when it's not the case at all. Debugging errors in undocumented code that involves several complex/opaque structures, nested function calls, and external libraries is not fun when you can't tell what step is at fault due to side effects, internal computations etc. not being clearly visible.

[bravetraveler]

That's completely fair!

There have been cases where very slight changes in methodology completely fall apart - reasons varying. Timing, cache fit, and whatever else you may think of.

Jenkins is something I've been picking up lately, and the 'DSL' has a ridiculous number of quirks

[bsder]

> "Why" is a really good way to put it, like you say - doing "What" just repeats something a novice, possibly even a layman, could distinguish.

And "profanity" in code is almost by definition a "Why"-type comment.

You don't get upset and leave a profane comment unless you did a deep dive and realized the code does something absurdly horrible that took you far too long to figure out.

[froggit]

> You don't get upset and leave a profane comment unless you did a deep dive and realized the code does something absurdly horrible that took you far too long to figure out.

This describes my profanity use in comments perfectly. I'll even increase the amount of profanity and "descriptive phrases" depending on the frustration level I peak at.

Fun fact: my profanity will always be formatted into proper, grammatically and contextually correct sentences. This seems counterintuitive.

I'm curious what kind of profanity other people use; whether anyone else has an oddly specific format or if it's more off the cuff. (fyi: edited to not be cussing on HN, there will be a 100% chance my first profanity will be :"f###ing bulls##t," this is usually enough. In more severe cases I'll generally add: "bloody h3ll," "raging dumpster fire," "dumbest s##t ever," "d#mnation! h#llfire!," and, when I've completely lost my s##t, "what in the actual f###ing s##t is this g##d##n f###ing bats##t f###ing insane s##tshow clusterf##k!"

It saves a lot of time down the road to know whether I got pissed, super pissed, pissed af, threw some random s##t, or "welp, it's 5 o'clock somewhere."

[Groxx]

Yeah. It's deep-dive "oh God it's all terrible isn't it" discoveries, often containing some of the cursed knowledge that was obtained, not

    // this shit implements fizzbuzz
    fizzbuzz()

[chinchilla2020]

I have been known to leave long comments or links to confluence for the purposes of QA and testing. Sometimes integration tests require special utils and in the worst case code modifications to work properly in a mocked production environment. Often this is outside the control of my own working group since I tend to work for giant megacorps.

Any tester is going to need detailed information that is devopsy and cannot be expressed in pure code (Despite the claims spoken by the code-as-infrastructure tools).

There are also cases where I like to document the living shit out of my classes/functions if they are something that will be used by many other devs. Bash/unix functions are some of the most heavily-documented tools you will ever see. Try using 'man grep'.

There are more questions than "why" that can be answered by comments. There are also "What ifs" that you could anticipate. Many of those "what ifs" are almost certain to appear in certain circumstances, and I choose to drop a few breadcrumbs that can save the code maintainers a few weeks of their time rather than following a false lead.

The beauty of code comments is that they don't require some external tool. They are in the pudding with the code itself, where they can be found easily. Most IDEs allow you to collapse long comments and even fade comments into a light grey so they aren't distracting.

From this thread and work experience I know that the code commenters are losing our war and are pretty much defeated by the code aesthetics crowd - who insist code should be beautiful before being useful.

[7thaccount]

Ever read a Fortran code base? I once worked with a vendor that had nearly zero documentation, but at least you could get source and it was very well commented. You could spend a few hours and actually learn what was going on. The comments helped get enough of an idea to where reading the code wasn't too bad. I don't think I would've had the patience to only read the code without some assistance in what I should be looking for.

[danans]

> . Best practice is to comment “why” something was done, not “what” is being done, or “how”.

I disagree about the "how", at least for challenging to read sections of code. In these instances, it is not good to assume that everyone who is reading or modifying the code is an expert in the language or problem domain, so it's good to explain to them how code solves the problem.

Explaining how the code works is very different than explaining what the code is doing. For example, something like "This code takes input sets of timestamp data and uses a timestamp keyed hash map to bucketize them by n minute interval".

That is very different than explaining how at each step you look at each time stamp and bucketize it, then generate a new time stamp bucket key and add it to the hash map.

The first approach explains at a very high level what's happening technically so that the reader can more easily understand the operations needed to accomplish the objective.

[rootlocus]

    def group_by_interval(timestamps, interval_duration)
        # do the stuff

Why does this require a comment?

[danans]

Who said require? I said it's nice to any future reader explain the algorithm if the implementation is complex. I've certainly benefited from such explanations in code.

[dylan604]

in procedurally written scripts, i write "what" comments as an outline or roadmap. i also use # vs // differently where the // style designates these what so i can find next to jump to next section. if i ever get away from being a solo dev and work as part of a team, there'll be a lot of unlearning personal habits

[andruby]

What you describe as sections seem like natural breaking points for function. Split of those section in their own named function. The names help to document, make it easier to test and the calling of the functions will give a high-level overview of the processes

Ie:

  def drive
    turn_ignition()
    shift_gear()
    press_accelerator()
  end

  def turn_ignition
    … code
  end

  def shift_gear
    …

[chrisjharris]

I think this is exactly right. Function names actually fulfil the role of documentation really well. I personally tend to make them long and quite verbose, like

`def start_the_car_and_accelerate`