I remember reading that people who swear a lot are statistically smarter. I'm sure there are lots of caveats to that, as with the code.
How long will it be before someone who doesn't understand causality starts encouraging developers to write profane comments? It wouldn't be any more absurd than lots of other non-causal behaviors I've seen pushed because somebody successful does them.
Failing to provide the typical social signals seems correlated either with extreme competence - they don't need to use polite language or other signals to boost employability - or with complete incompetence. There's a skill floor that cuts off the latter from this dataset when they can't configure an SSL certificate for their git client; their curses at "unable to get local issuer certificate" or "fatal: repository not found" are not uploaded to the Internet.
I believe Nassim Taleb wrote about this in relation to 'virtue signaling' - not swearing being a sign that people are trying to 'signal' professionalism in order to keep their jobs, and therefore are more likely to have less actual professional skills (which if good enough would secure their jobs regardless of profanity) and vice-versa. Same for hoodies over ties, etc. Although all this probably gets flipped now that we have people writing papers like this - context is everything.
> I remember reading that people who swear a lot are statistically smarter.
I'd need more evidence of that. My anecdotal experience is that saying "fuck" a lot is indicative of a lack of imagination. For example, Winston Churchill's legendary devastating insults, with no profanity necessary.
I'd bet a lot of the non-profanity code is people open sourcing code just to be impressive on resumes or for school, where the profanity code is probably real code.
Sounds likely to be a classic case of correlation != causation
Can they though? Like sure its pretty easy to idly speculate, but instead of doing that they decided to claim the opposite. My claim, well i wouldn't call it baseless since its based on the study protocol in TFA, certainly might be wrong. But the opposite claim is almost surely wrong, to the point of being absurd. Which is the claim they made.
I remember there being a startup in the Dotcom era, I forget the name but for people familiar with Cambridge, MA it was where the IDEO is now. They were notorious for a few things, but one of them was writing open source software with a lot of profanity.
I thought this was cool, and was talking excitedly about it to my boss and some of the senior devs. They were less amused. Cut 20 years later and I too am less impressed by this.
Not that I think it's *bad* per se, I'm not clutching pearls or anything. But I never find myself thinking what the code really needs are profanities in the comments. Whereas back then I thought it'd be funny/cool and went out of my way to do so when I could. Which wasn't often.
I wonder if swearing can help "free the mind" in some way, with the "rebellion" opening up more, perhaps non-standard/out of the box, "fucking good" ideas?
Yeah. Speaking without profanity always makes me feel a little irritated and constrained. Not because I only know how to speak with profanity and use it as a crutch, but because I use both profane and non-profane words as tools to convey a wider gamut of nuance. So shrinking my lexicon is shrinking my dynamic range
I hear this, comments generally should not draw attention to themselves. For this, short & terse win. I routinely look to cut any unnecessary words from comments.
It was the most painful code review where I asked someone to remove a joke they wrote in the comments. It was a good joke, funny, short, in good taste, I loved it, but.. distracting and unnecessary.
Swearing for the sake of it does look childish, yes. I've noticed that in a few streaming TV shows, where they've gotten too excited over a lack of censorship that they just end up looking like teenagers who still think saying "fuck" is an act of rebellion
On the other hand, I'd like to write something like "this is a bit shit but will be replaced later" because that's how I naturally speak. Sanitising it to "crap" or "poor" just makes me feel like I'm teaching a youth club or something, and it is a minor pipeline stall in my train of thought while I do a mental synonym search
I mean i think the article is implying that. However i think the bigger thing is the correlation is misleading due to the sample being the long tail of github projects, which i dont think is representitive of "production" open source projects and certainly not software in general.
Rorschach test for programmers: give your confident gut feeling explanation for this phenomenon.
I'll do mine: there's likely a correlation between needing to maintain a professional conduct which includes forgoing foul language (you're programming at work) and writing code under time pressure where getting a product ready for release is more important than strict adherence to clean programming practice (you're programming at work).
My gut feeling: when you start to submit swear words in your code, it indicates that you "breathe" the code and know it in and out.
The other extreme: if you have no idea what you are doing, you might try to mimic "corp speak" in your code to hide the fact that you actually have no clue.
In other words: it needs some confidence in your ability to assess some aspect of the code in order to use swear words.
Take almost any two things like this and you're actually virtually guaranteed to draw out some weak, but quite likely statistically significant, correlation.
What lies behind that correlation is probably a entropic mishmash of so many factors that it defies human explanation, and also, defies any attempt to try to "harness" the forces that seem to appear. It could be that all the siblings to the comment are right all at once.
I'll cop to just glancing at the graphs, but they don't look out of line for this effect to me intuitively.
Also backing this is that more-or-less the same article/thesis could easily have been written for the opposite correlation.
The developer who knows what they're doing is also more likely to be 1) overworked because they do much of the useful stuff and 2) cognizant of bureaucracy which gets in the way of them doing useful stuff.
This seems unlikely to be true in this case because the study was looking at github projects, and it seems unlikely the sample had enough code from "uptight" work places, to have an affect one way or another
Nobody suggested causation. The idea that you can improve code quality by adding profane comments is so self-evidently absurd that nobody would even suggest such a thing. Except you kind of just did.
Correlation is not causality. Swearing in the comments will not magically make your code better, but fixing a hidden bugs that you have been chasing for weeks will certainly make you swear when fixed.
Sounds like you're suggesting a causal relationship the other way, though. As per this explanation, putting effort into debugging edge cases will statistically cause the comments to swear more.
I'm fond of pointing out, despite every time I get downvoted, that causation is the thing we have no knowledge of, and therefore correlation is all we have. As Feynman said about gravity, there is no how or why to gravity, as far as we know it's simply a property of matter. But of course, that means we only know that because of the perfect correlation between matter and gravity, including every time we conduct an experiment about it; but still we have no cause to point to.
While that may be the case, the correlation coefficient of matter and gravity is so close to 1 that we can't tell the difference and the correlation coefficient of swearing in code to good code is far less.
A reasonable working definition of causality, used by almost all scientists today, is that X causes Y if a change in X, unaccompanied by any other change, changes Y. At root, this is indeed a statement about correlations, but it's a special kind of correlation, which is hard to estimate from observational data where many other things may change along with X.
I'm sure the top comment here will be something like "this is invalid because no way can you assign a numerical value to code quality! wtf?!"
I'm withholding my own judgement on that.
For anyone curious, the authors are coming up with a code quality score using an open-source tool called SoftWipe[0]. From the paper:
> SoftWipe is an open source tool and benchmark to assess, rate, and review scientific
software written in C or C++ with respect to coding standard adherence. The coding
standard adherence is assessed using a set of static and dynamic code analysers such
as Lizard (https://github.com/terryyin/lizard) or the Clang address sanitiser (https:
//clang.llvm.org/). It returns a score between 0 (low adherence) and 10 (good adherence). In order to simplify our experimental setup, we excluded the compilation warnings, which require a difficult to automate compilation of the assessed software, from the analysis using the --exclude-compilation option.
I sometimes feel like swearing in the comments or commit messages, which can be the first thought coming to mind, and spend a few resources on writing in a kinder way.
Perhaps I could use this as an excuse for not reaching a deadline...
Possible explanation: swearing is more likely to be committed into code by people who either (1) own the code, or (2) know they're too valuable to be punished. So it self-selects.
I personally have very different commenting styles between my work and personal projects. Not that any of it's good.
Alternative explanation in the same vane as your theory:
The cognitive and time cost of compliance for language policing takes away from valuable programming and planning involved in developing solutions. (i.e. "banned words" [swear words] and politicalized words [whitelist/blacklist,etc])
Antoher possibility is the people who don't want to deal with that are gone and we're seeing a loss of their contributions.
It's really not a big leap, though. People who are afraid of violating a code of conduct because they're "under the watch of language police" are basically experiencing a form of anxiety that may or may not have a basis in reality.
Being afraid of being sent to the HR DEI board because you named a process 'Child1' then ran Kill(Child1) ... or any less obvious scenario similar to that ... is not going to do great things to your ability to work.
"Oh, THEY are policing my language. THEY are watching everything I say!"
You're reading the idea of language policing as some actual thing, like people are hanging over someone watching every word they say. It certainly might be true in some offices or with some coworkers, but, I'm pretty sure feeling that your every word is policed is closer to a form of anxiety than an actual problem in most offices.
Or, your coworkers are basically bullying you over minor nitpicks, which will keep you in a state of mild anxiety.
Either way, having to monitor your every word is definitely closer to being anxious than not, and is definitely going to have some impact on your performance.
> You're reading the idea of language policing as some actual thing, like people are hanging over someone watching every word they say.
I’m not sure where you got that impression. I didn’t say anything like that anywhere. You’re just making assumptions in service to what appears to be some axe grinding.
the point here being: the perception of being surveilled by "language police" on its own is either anxiety inducing or the result of an existing anxious disposition.
The actual act of "language policing" is also going to induce or worsen an existing anxious disposition.
I would also argue that it prevents important technical conversations and accounting. If you have a m/s architecture, and you're concerned about redudancy/cost/etc.. well that conversation has been delayed and potentially prevented over the constant correction of saying manager/worker instead. It's a mental/cognitive/communication tax on the contributors.
Agree. You'll never get a count of all the people who may have been interested in contributing to a project but decided against it because of a COC or language police.
Yep. I keep noticing that places which tell everyone how "inclusive" and "welcoming" and "safe" they are have a strong correlation with being hostile, unsafe spaces where you're walking on eggshells with the implicit threat of dogpiling and vicious character attacks. Nothing says "friendly" like a big list of rules on the front door, and being told "you can feel safe here because we support hunting those unsafe witches!". This applies well beyond just FOSS projects
It's sort of like the stock horror media trope where a community that projects a facade of being a happy utopia is maintained by unspoken but vicious enforcement of conformity
exactly, those who scream loudest about these things tends to be the biggest offenders themselves. There is an old saying: "thief thinks every man steals". This is of course not a 100% rule, but odds are generally good :)
I guess I should put it another way. Sure it’s a valid theory, but I think asserting it as borderline self evident/a big enough deal that it primarily explains the profanity in repos is another matter entirely. I could also assert 5 other valid theories I’m sure. Doesn’t mean they’re all accurate or worth weighing.
So yeah, I’m just curious how those of you who responded to me are quantifying this.
If I find someone with 20 years experience that disagrees with your take, what then? I’m just wondering how y’all are quantifying this, as I explained in another comment.
The author of the paper suggests it's because the author of the code cares more, and is more passionate. Do you think it's just random chance there is a correlation, or do you have a better explanation for the results?
I skimmed the paper, and it looks like they are looking for swearing _anywhere_ in the repos' code, not just comments.
I would be curious to see the ratio of swearing in comments vs code identifiers. I'd also be curious to see if the repos with swearing in their comments just have more comments in total. Perhaps the correlation is, "code with more comments is more likely to be higher quality".
The best programmers I've worked with swore at their coworkers regularly, but never in their code.
They were not great people, and I'd happily kick them in the face if I would encounter no legal or professional repercussions, but, there definitely does seem to be some correlation (in my experience) between being abrasive and being a skilled programmer.
RIP. Likely the Platonic Ideal of an abrasive programmer.
I'd put mid 00s Linus Torvalds as the apotheosis. Despite being an incredibly abrasive person, he has left a mark on history.
Swore at or swore while talking to? There's quite a big difference. I don't see profanity as inherently abrasive, and some of the biggest dickheads I've met in workplaces didn't swear much at all (some were of the Professor Umbridge type, so kept up an air of perfect professionalism)
literally right there in the comment. "swore at regularly".
Anyways, I definitely agree that swearing isn't the same as abrasive, but swearing at people is definitely an abrasive trait. Also agree that some of the biggest dickheads around keep up an air of professionalism.
The jury is still out if I'm a good programmer, but I did one time need to use a hashmap that had to grow to about ~100gb in size. Because of that, I ended up calling it "bigassHashTable".
It makes me happy that it remained being called that for quite awhile.
I remember a day at a previous job when our CEO came in and told us we weren't an early stage startup anymore and had to start acting like it. Remove profanity and inside jokes from the code, and no more Quake during lunch breaks. Morale took a big hit that day.
if a CEO did that to me I'd just tell him to pull the stick out of his ass. none of it has anything to do with maturity.
but I'm relatively old.
you can Quake (or Overwatch or whatever the current game is) during lunch breaks at every FAANG, for christ's sake. (it's different if you're playing it during working hours.)
Yeah. Joking around helps build camaraderie, and makes people want to stay working there. I'm not sure who or where these hypothetical pearl clutchers, who can't handle a codebase with jokes or a bit of swearing, are, or why management care so much about them hypothetically encountering the codebase and getting upset. Sanitising everything and making it family friendly just makes workplaces even more soulless, rather than letting us have a bit of character in our work. At best it makes you look humourless, and at worst it can make people feel anxious about causing offence, if it's particularly strict policing
Or that those that need to adhere to strict linters, formatting, etc are less happy with their life and thus use more profanity. eg. "code quality" tools that does not have any benefits besides finding potential bugs that does not effect the state of the program, like lines that are 71 characters long instead of 70 characters.
> 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.
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.
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.
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.
> 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.
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
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.
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.
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.
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.
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.
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.
- 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.
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.
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.
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.
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.
> 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.
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.
My pet theory is that this is because honest, emotional comments are much more useful than the usual “professional” style that try to hide it when you have no clue what you’re doing.
When it’s clear someone was stuck, frustrated, banging their head against the wall etc while writing a particular bit of code, you can refactor a lot less defensively because you know the crappy parts weren’t secretly there for a reason.
I love real, honest, emotional comments. Pour all the frustration in there. Future you and your colleagues will thank you.
> Next, Strehmel and his team quantified the compliance of these two different sets of open source code with coding standards. The results were presented as an indicator of the quality of the source code through the SoftWipe tool.
I would read that study as coding standards lead to profanity. (Not sure wether or not coding standards should be correlated with code quality, I just think it is obvious that the measure is correlated with the conclusion in an obvious way.)
[Post posting:] Also looking at the plots, it seems that the two distributions are different, first the swear word distribution seems to be wider and second it has a clear outlier at "software quality" 8, so if anything it is an indication that something much more complex is going on.
> Much of the community considers profanity as a vulgar display of lack of intelligence and education, because why use profanity when you have a rich vocabulary?
in other words, it increases the chance that the programmer is in a specific locale (like the US?) such that the location has less bad programmers than other locations.
And probably, increases the chance that the person is fed up with fixing someone else's code - hence the anger
Isn't there a study that shows that people can tolerate pain better when they swear? This doesn't really surprise me.
I'll swear in my code if I really feel like it but commits and everything else I keep more presentable.
It's just that you've evolved biological filters that "block" the swearing from getting voiced out as being presentable takes the priority? The way our society is progressing right now, such evolution seems to be the direction that we all will take eventually.
Probably same goes about the people? The emotionally charged person that swears and gives a mouthful usually ACTS better than the cold calculated one that speaks the right words but full of cunning inside?
220 comments
[ 2.6 ms ] story [ 255 ms ] threadHow long will it be before someone who doesn't understand causality starts encouraging developers to write profane comments? It wouldn't be any more absurd than lots of other non-causal behaviors I've seen pushed because somebody successful does them.
“What the f… heck is this, kiddo?”
Definitely gotta utilize those brain wrinkles in that case.
I'd need more evidence of that. My anecdotal experience is that saying "fuck" a lot is indicative of a lack of imagination. For example, Winston Churchill's legendary devastating insults, with no profanity necessary.
Sounds likely to be a classic case of correlation != causation
if (*some_bullshit >= shit_tolerance){
fucks_given = 0;
exit(IM_DONE);
}
mmm
/embeddedme says it could be a memory-mapped peripheral that needs to be reset on exit. But that's a stretch.
Why am I even thinking about this?
I thought this was cool, and was talking excitedly about it to my boss and some of the senior devs. They were less amused. Cut 20 years later and I too am less impressed by this.
Not that I think it's *bad* per se, I'm not clutching pearls or anything. But I never find myself thinking what the code really needs are profanities in the comments. Whereas back then I thought it'd be funny/cool and went out of my way to do so when I could. Which wasn't often.
It was the most painful code review where I asked someone to remove a joke they wrote in the comments. It was a good joke, funny, short, in good taste, I loved it, but.. distracting and unnecessary.
On the other hand, I'd like to write something like "this is a bit shit but will be replaced later" because that's how I naturally speak. Sanitising it to "crap" or "poor" just makes me feel like I'm teaching a youth club or something, and it is a minor pipeline stall in my train of thought while I do a mental synonym search
I'll do mine: there's likely a correlation between needing to maintain a professional conduct which includes forgoing foul language (you're programming at work) and writing code under time pressure where getting a product ready for release is more important than strict adherence to clean programming practice (you're programming at work).
Everyone post your favourite conjecture!
The other extreme: if you have no idea what you are doing, you might try to mimic "corp speak" in your code to hide the fact that you actually have no clue.
In other words: it needs some confidence in your ability to assess some aspect of the code in order to use swear words.
Places uptight enough that developers never swear in comments are uptight in other ways that lead to poor team dynamics which hinders quality.
Take almost any two things like this and you're actually virtually guaranteed to draw out some weak, but quite likely statistically significant, correlation.
What lies behind that correlation is probably a entropic mishmash of so many factors that it defies human explanation, and also, defies any attempt to try to "harness" the forces that seem to appear. It could be that all the siblings to the comment are right all at once.
I'll cop to just glancing at the graphs, but they don't look out of line for this effect to me intuitively.
Also backing this is that more-or-less the same article/thesis could easily have been written for the opposite correlation.
I'm fond of pointing out, despite every time I get downvoted, that causation is the thing we have no knowledge of, and therefore correlation is all we have. As Feynman said about gravity, there is no how or why to gravity, as far as we know it's simply a property of matter. But of course, that means we only know that because of the perfect correlation between matter and gravity, including every time we conduct an experiment about it; but still we have no cause to point to.
> This means that swearing will not automatically improve the quality of your code.
I'm withholding my own judgement on that.
For anyone curious, the authors are coming up with a code quality score using an open-source tool called SoftWipe[0]. From the paper:
> SoftWipe is an open source tool and benchmark to assess, rate, and review scientific software written in C or C++ with respect to coding standard adherence. The coding standard adherence is assessed using a set of static and dynamic code analysers such as Lizard (https://github.com/terryyin/lizard) or the Clang address sanitiser (https: //clang.llvm.org/). It returns a score between 0 (low adherence) and 10 (good adherence). In order to simplify our experimental setup, we excluded the compilation warnings, which require a difficult to automate compilation of the assessed software, from the analysis using the --exclude-compilation option.
[0]: https://github.com/adrianzap/softwipe
Perhaps I could use this as an excuse for not reaching a deadline...
I personally have very different commenting styles between my work and personal projects. Not that any of it's good.
(But I concede that effort and productivity are not the same thing.)
"This is bullshit" is an important realization. If you can't say it, then things will stay miserable.
The cognitive and time cost of compliance for language policing takes away from valuable programming and planning involved in developing solutions. (i.e. "banned words" [swear words] and politicalized words [whitelist/blacklist,etc])
Antoher possibility is the people who don't want to deal with that are gone and we're seeing a loss of their contributions.
It's really not a big leap, though. People who are afraid of violating a code of conduct because they're "under the watch of language police" are basically experiencing a form of anxiety that may or may not have a basis in reality.
Being afraid of being sent to the HR DEI board because you named a process 'Child1' then ran Kill(Child1) ... or any less obvious scenario similar to that ... is not going to do great things to your ability to work.
You're reading the idea of language policing as some actual thing, like people are hanging over someone watching every word they say. It certainly might be true in some offices or with some coworkers, but, I'm pretty sure feeling that your every word is policed is closer to a form of anxiety than an actual problem in most offices.
Or, your coworkers are basically bullying you over minor nitpicks, which will keep you in a state of mild anxiety.
Either way, having to monitor your every word is definitely closer to being anxious than not, and is definitely going to have some impact on your performance.
I’m not sure where you got that impression. I didn’t say anything like that anywhere. You’re just making assumptions in service to what appears to be some axe grinding.
Language policing slows down technical progress, very significantly I would wager.
It's sort of like the stock horror media trope where a community that projects a facade of being a happy utopia is maintained by unspoken but vicious enforcement of conformity
So yeah, I’m just curious how those of you who responded to me are quantifying this.
Who's the narc on your team that would even point it out? It's not like HR has some commit hook on the repos filtering for this stuff...
I would be curious to see the ratio of swearing in comments vs code identifiers. I'd also be curious to see if the repos with swearing in their comments just have more comments in total. Perhaps the correlation is, "code with more comments is more likely to be higher quality".
They were not great people, and I'd happily kick them in the face if I would encounter no legal or professional repercussions, but, there definitely does seem to be some correlation (in my experience) between being abrasive and being a skilled programmer.
Anyways, I definitely agree that swearing isn't the same as abrasive, but swearing at people is definitely an abrasive trait. Also agree that some of the biggest dickheads around keep up an air of professionalism.
It makes me happy that it remained being called that for quite awhile.
but I'm relatively old.
you can Quake (or Overwatch or whatever the current game is) during lunch breaks at every FAANG, for christ's sake. (it's different if you're playing it during working hours.)
> 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.
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.
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.
Code gets out of date as well, so let's just stop writing it altogether..
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
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.
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.
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.
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."
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
Ie:
`def start_the_car_and_accelerate`
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.
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.
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.
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.
Sidecars generally suck because they get lost.
Just use comments.
You're not supposed to change commit messages.
The correct lines to blame are the ones right there, not exactly rocket science
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?
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.
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.
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
- 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.
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 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.
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.
A piece of code with a lot of swear words for variable names but no comments at all would be an extreme example.
I think that's a very safe assumption. People don't generally use profanity for actual code (variable or function names etc.).
I wouldn’t be surprised if code quality goes up with comment curses and down again with commit message curses.
You can really feel the author's rage at the state of the world.
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.
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.
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.
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.
paper: https://cme.h-its.org/exelixis/pubs/JanThesis.pdf
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?
When it’s clear someone was stuck, frustrated, banging their head against the wall etc while writing a particular bit of code, you can refactor a lot less defensively because you know the crappy parts weren’t secretly there for a reason.
I love real, honest, emotional comments. Pour all the frustration in there. Future you and your colleagues will thank you.
Everyone swears sometimes. If you never do it in front of others, it signals that you're always filtering yourself.
I would read that study as coding standards lead to profanity. (Not sure wether or not coding standards should be correlated with code quality, I just think it is obvious that the measure is correlated with the conclusion in an obvious way.)
[Post posting:] Also looking at the plots, it seems that the two distributions are different, first the swear word distribution seems to be wider and second it has a clear outlier at "software quality" 8, so if anything it is an indication that something much more complex is going on.
But one of my favorite projects to ctrl-f for "fuck" is in the jedi outcast source code. Since it is proprietary and was a good game: https://github.com/search?q=repo%3Agrayj%2FJedi-Outcast+fuck...
https://www.youtube.com/watch?v=R_b2B5tKBUM
lolwat
Why not use the full range of one's vocabulary?
Or by "full range" did you mean "limit it to a few well-worn cliches"?
And probably, increases the chance that the person is fed up with fixing someone else's code - hence the anger