Hacker News Reader

Comment by whoopdedo | Hacker News Reader

From the research paper:

> we calculate the swear factor as the number of swearwords divided by the lines of code

That's what I suspected. Assuming that most swear words will be contained in comments, what this is actually measuring is the ratio of comments to code. In other words, code that is more heavily commented is better.

I think we already knew this.

That said I would like to see a more critical analysis. First control for comment density. Then compare code quality to swearing in comments and also variable names.

View on HN

It is anecdata, but I can confirm this is the case for my code.

I tend to focus more on documenting the surprising code paths, not the mundane. And when my code needs to do something special because some other component (library, hardware, API) has issues, there's usually some colourful language describing the sad state of the world outside my control.

that's *** brilliant I @#@#@ know that feeling

Also any mature, well maintained code will have found a lot more of those truly ‘wtf’ bugs and edge cases, which often involve same colourful language when we finally figure them out.

>...code that is more heavily commented is better. >I think we already knew this

Who's "we"?

In my many years of software development, I've found a very large fraction of developers use very few, or even zero comments, and it's getting worse. Just look at the posts below here: there's a bunch of people arguing that comments are useless or harmful. It's no wonder that software sucks so much these days, since apparently no one believes in documentation or code maintenance any more.

> It's no wonder that software sucks so much these days, since apparently no one believes in documentation or code maintenance any more.

I think this comment explains why software gets worse in many cases:

> Of course nowadays, this is legacy nonsense. Everything uses UTF-8 for "char", and what doesn't is broken and terrible anyway. But the old ways stayed with us, and the stupidity of it as well.

The problem is the "legacy nonsense" tends to accumulate over time & as people depend on it, takes a long time to finally remove.

> They are so hilariously misdesigned and insufficient, I can't even fathom how this shit was _standardized_.

They did their best given their circumstances & abilities. Now we must forever pay the price.

> Several decades later, the moronic standard committees noticed that this was (still is) kind of a bad situation. Instead of fixing the situation, they added more garbage on top of it. (Probably for the sake of "compatibility").

At least they tried...

> All in all, I believe this proves that software developers as a whole and as a culture produce worse results than drug addicted butt fucked monkeys randomly hacking on typewriters while inhaling the fumes of a radioactive dumpster fire fueled by chinese platsic toys for children and Elton John/Justin Bieber crossover CDs for all eternity.

Yeah! Time to get back to work...

Credit to https://news.ycombinator.com/item?id=36626018 for pointing this out.

> In other words, code that is more heavily commented is better.

It could also be that understanding code in any non-trivial project is likely to back the developer into a corner where they become frustrated and swear at the computer.

More importantly, the lack of swearing might be a sign that the devs lack the competence to know when they are cornered.

By the time you are swearing in your comments, I'm pretty sure you know you're cornered

I think anger is a sign the developer actually cares about what they are doing. In my experience, people who don't care aren't at all irritated by the imperfections of the software they have to use, they just accept it, slay their dragon and move on. People who care tend to get very angry about what's ultimately philosophical matters.

That bares the question whether it’s healthy to care so much about code it makes you angry. Being able to slay dragons instead of arguing what the perfect angle to cut off their wings is might be a benefit after all.

The question of whether it's more profitable not to care is easier to answer: it definitely is.

Software reflects our understanding of the problems and concepts at hand. Good software implies developers who understand what they are doing and why they're doing it. The reality though is that good software is almost always not actually necessary. Corporations are perfectly happy pushing out minimum viable products as fast as possible.

He don't seem to use the swear factor anywhere. The actual statistical comparison (Table 3.1) is simply mean SoftWipe score of repos with swears (5.87) vs. mean SoftWipe score of repos with 4+ stars (5.41). The increase is due to 2-3 clusters of swear repos with SoftWipe score ~7.5 and ~20k lines of code. It seems like he deduplicated the repos based on URL, not content, and Github could have biased the results returned in the GitHub search, so I wonder if it is simply sample bias.

paper: https://cme.h-its.org/exelixis/pubs/JanThesis.pdf

as long as we’re designing the ideal experiment for someone else to do, let’s throw in the commit messages as well.

I wouldn’t be surprised if code quality goes up with comment curses and down again with commit message curses.

My favorite infamous example being the MPV C locale commit: https://github.com/mpv-player/mpv/commit/1e70e82baa9193f6f02...

You can really feel the author's rage at the state of the world.

That's a great rant, and not unjustified. I feel with the author.

The observation of the association is already valid since it doesn't try to say anything that no one can say.

Saying "control for comment density" presumes one knows how to even do that or how to even define it.

How do you decide that a given line of code or comment should weigh more or less than another?

If a codebase has both a lot of swear words and a lot of all other words, so what?

That assumes that most comments contain cursing.

No it doesn’t. If any more than 0% of comments contain profanity, then on average code with more profanity will be better.

Not quite.. You still have to assume that there is more profanity per comment than per (uncommented) LOC.

A piece of code with a lot of swear words for variable names but no comments at all would be an extreme example.

>You still have to assume that there is more profanity per comment than per (uncommented) LOC.

I think that's a very safe assumption. People don't generally use profanity for actual code (variable or function names etc.).

Isn’t commented code no longer considered a good idea in most companies?

I used to work for a bank and the policy is no comments unless absolutely necessary, because comments become out of date. Doxygen is the only real comments allowed.

I'm not sure the ratio of comments to LoC is a sign of good quality code.

Too many comments might actually be a bad thing. It's more lines to maintain, and sometimes the comments just tell what the code is doing where there is no need to.

I find that comments are most valuable when onboarding/understanding an unfamiliar code base. Comments composed of a little bit of “what” some “where” and a lot of “why” seems best for this scenario.

Wow, that seems strange to me. Seems like the policy should be to make comments when needed, and keep them up to date.

That's an idiotic policy and definitely not something that is industry standard.

Code gets out of date as well, so let's just stop writing it altogether..

Even better, lets triple the work and require UML diagrams, comments, and code to all be in sync at all times!

you left out keeping the docs in sync as well

don't forget the random google sheet that the project manager wants to keep updated

If code is wrong or out of date, the program will fail or stop doing that it's supposed to do. If comments are wrong or out of date, it will mislead the developer or at least confuse them if the comment says something else than the code. A wrong comment is worse than no comment - and usually developers don't care about comments as much as for the code. Why comment some code anyway if the code is easy to read? The only reason is to explain -why- something has been developed, not -how-.

The identifier can become out of date. The common argument against comments is that they're an indicator that you should factor that block out into a function with a descriptive name, but I can say for certain that method names can easily become out of date. As for doing neither, well at the end of the day you probably do want a way to summarise a block of code to the next human, rather than requiring them to read every statement

Actually, speaking as someone's who's been generally critical of the "get AI to write our PRs!" thing, having an AI attempt a quick sanity check of comments near where your edits are could maybe work well

the code can't get out of sync with itself. i agree, that's a dumb policy. boilerplate comments are just as bad as boilerplate code-- the policy should be to comment when something is notable, in the manner that's appropriate for the context.

but comments telling you one thing is happening when something else is happening is a problem, and i suppose it couldn't happen if the comments weren't there.

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.

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

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

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

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

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.

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

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

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
    …

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`

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.

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.

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

    def group_by_interval(timestamps, interval_duration)
        # do the stuff

Why does this require a comment?

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.

No, that is stupid. People just don't want you to write comments like

    // Set foo to true
    foo = true;

Somebody saw one too many comments like that and overreacted. As long as you a) don't write comments describing what is self evident from the code, and b) try to make the code as descriptive as possible, then it's fine. Comment away.

it's not always as simple as that. what if you once implemented some facade method to get data from database like "findProductById" and you comment it with "finds a product from database by it's ID". later on, someone (maybe you) replaced some deeper logic here, so the product might be fetched from some other source, depending on some configuration. in case you didn't even touch the facade file, will you remember to update the comment? most developers will not. this risk is ALWAYS present if the comment explains more than the nearby code. so a comment is only safe if it contains the same degree of information like the nearby code. in that case though the comment is redundant. comments only make sense if they explain the -why-, not the -what- or -how-.

First of all you shouldn't comment "finds a product from database by it's ID" because that's just what the function name already says.

Second, you're (I think) arguing that we shouldn't use comments because they might go out of date, which I think is throwing the baby out with the bath water.

> comments only make sense if they explain the -why-, not the -what- or -how-

That is the wrong heuristic. Comments make sense if they provide useful information that isn't self-evident from the code. Often that is the "why", but it can also be the "what" or the "how". Think about something like the fast inverse square root. A comment explaining how it works is very valuable.

Besides, even function names can go out of date, yet we still give functions meaningful names.

That still valuable as it explain the original intent of the code, especially together with vcs history. When debugging strange issues even cryptic hints can be useful. Even merely the fact that someone thought that commenting a specific bit of code was required can be valuable.

If you have a process where every commit is well documented, you don't need much comments since you can rely on whatever is your analogue for git blame. It's not a lack of comments, it's actually the opposite but aside from the code base.

When I worked at SAP where VCS for ABAP is ancient and has no analogue for git blame we had a practice of putting a SAP Note next to every code change, since some of the things that we had to implement are dictated by business/legislation, so you need a proper explanation from time to time. Without it, the code becomes unmaintainable.

That requires everyone to have access to the repo, and to wade through it looking for changes to the relevant area of code you're working in. That sucks.

In which situation would you not have access to the repo? I guess if it's a library or something, but libraries must always be documented in a different way to business code.

Maybe you're a contractor. Maybe it's legacy code that has simply been archived. Maybe the network is down. Maybe there was a bad migration.

Sidecars generally suck because they get lost.

If that's the case, you have bigger problems than documentation

Like what?

Relying on commits also fails as soon as feature branches start being squashed. And the comments in commits can’t be modified over time. You have to hope readers “git blame” the correct lines of your code.

Just use comments.

Don't squash. If you insist on it, I can't imagine why you wouldn't squash the commit messages

You're not supposed to change commit messages.

The correct lines to blame are the ones right there, not exactly rocket science

If your git squash contains all the commit messages, it’s a pain to figure out which commit message refers to which line of code.

A comment goes right there. No tools needed. Mutable. Readable. Contextually in place. And you can even add comments while coding without waiting for the commit.

Is typing // really so much effort?

No it's not and neither is writing a proper commit message. That's why you do both, but most of it goes in the commit. Like in the Git project

I get where they are going with it - every block of code should probably be obvious and final since it has one item to do well. Unfortunately there are always times when n random fields will be used for a conditional that is completely non-obvious. Comments will always be necessary to some degree.

that's why three and I think the fourth will leave our company after original developer left undocumented and hard to understand code (it's pretty complex and has tons of hacks to work on different OS'es), first year they learn what the hell is that code, how it works and they are not allowed to comment anything (I asked few times why we waste so much time for basic stuff, they said it is unnecessary...ok I guess). Now they hired original developer for tons of money just to consult newest developer and explain him code. Reasonable I guess.

While I carefully keep others away from my code the notes say I have a complicated relationship with my future self. While comments should be the least useful to me I've tried many formats and found that it is spectacular to have the full elaborate comment above each bite sized nugget of code. I mean that what was solved as a single thing after breaking down the larger problem.

The result is that I don't read any code at all. The whole thing is compiled to the native format that is human language. The code is great for illustration.

If I keep it in separate files as documentation it takes to much effort to find and update. It takes needles extra effort and is less precise.

It is just a personal preference of course but if one had any experience writing code in any language it should be easy to grasp say at 4 am while drunk.

No-comments are better than low-effort, low-quality, unmaintained comments, for sure.

You can imagine a world where all the projects that aren't realistically going to spend the effort on high-quality maintained comments makes the correct choice to skip comments unless absolutely necessary. And where projects that are realistically going to put effort into high-quality, maintained comments, do so.

In this world, comment density would correlate highly with code quality per line of code. Profanity might not, I'm not sure. I do think you'd still find profanity in high-effort, high-quality, maintained comments, but it might indicate lower quality surrounding code, not higher.

And it would still be unclear whether the existence of comments are a cause of higher quality code, or just a proxy for amount of effort and care taken per line of code.

Pasting again my 4 reasons to leave a code comment:

1. An odd business requirement (share the origin story)

2. It took research (summarize with links)

3. Multiple options were considered (justify decision)

4. Question in a code review (answer in a comment)

And the article on how/what/why in code: https://max.engineer/maintainable-code

If the code doesn't speak for itself...

…then I would suggest altering the code to speak for itself. If you can't do that any further, refer to the 4 reasons to leave a comment.

And those meaningful relevant comments will be invisible in between those useless comments that were added to satisfy some tool that counts them.

I’d also add:

- The code is not self describing for some reason (eg duffs device, complex math, non obvious cases, etc)

- The code is correct but it looks intuitively wrong. This comes up every few thousand lines for me, where some conditional looks redundant or twisted up for some reason - like maybe there’s weird choices to keep the borrow checker happy. I leave a note to myself because next time I read that code I’ll want to “fix” it.

- Internal function preconditions / invariants. Eg, “this method must only be called while the XXX mutex is held” / “this code can only be reached when YYY is true because <reason>”. Sometimes these checks can be cheaply expressed in assertions, but not always. And sometimes you need comments as well to describe the nuances of what’s going on.

Rereading my comment, maybe these are all examples of comments used to support code that’s not self describing. I’ve been programming for about 30 years now. I don’t think self describing code is always possible or desirable. I prefer fewer, longer functions with comments than digging through dozens of tiny functions spread everywhere. Large functions are usually easier to write and to read.

I agree with this, and some of this does come up in code review questions (point #4). Sometimes you can already predict a question or predict a mistake someone is likely to make, especially knowing your colleagues/context. In those cases a preemptive comment makes sense, but only if you couldn't somehow define that mistake/misconception out of existence in the code itself.

If you're curious to read a well-earned take on comments: http://antirez.com/news/124.

Inline comments are a reflection on the authors' abilities to write good comments. They can be kinda useless, actually-bad, or really helpful.

One canonical example of a "good comment" is explaining why a strange or not-the-least-complex approach was taken to implementing a certain solution. The code is like chesterton's fence, and the comment is a post explaining why it's there. That way, future readers can better assess for themselves whether it's worth their time trying to tear down the fence.

I never write comments, and I think they typically have a negative correlation to quality (this code is so f**ed up, plain english is, of all things, more clear and precise than code!). Unless you are releasing code publicly, and you are documenting the public API, I've never seen a valuable comment. I've seen plenty of harmful comments. However I wholeheartedly endorse using this otherwise useless but common language feature for swearing.

I think swearing in comments indicates you are unburdened by bureaucracy and pointy haired bosses (because they prohibit such things), which would certainly lead to better code.

you've never seen a useful comment?

I've been doing this for 20 years, so maybe? But I can't recall a single one excluding painstakingly maintained documentation for a public api where the source isn't readily available. I usually try hard not to read the comments and just read the code because comments are wrong so often.

Reply on news.ycombinator.com