8 ms·

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

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.

mr_00ff00 3y ago
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.
- almet 3y ago
  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.
  - brazzledazzle 3y ago
    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.
- makeworld 3y ago
  Wow, that seems strange to me. Seems like the policy should be to make comments when needed, and keep them up to date.
- paxys 3y ago
  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..
  - jacobsenscott 3y ago
    Even better, lets triple the work and require UML diagrams, comments, and code to all be in sync at all times!
    - dylan604 3y ago
      you left out keeping the docs in sync as well
    - chinchilla2020 3y ago
      don't forget the random google sheet that the project manager wants to keep updated
  - ckdot2 3y ago
    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-.
    - didntcheck 3y ago
      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
- flatline 3y ago
  It really depends on the comments. Best practice is to comment “why” something was done, not “what” is being done, or “how”. Every programmer can read code, most code should be pretty self-explanatory. But in any sufficiently complex routine, there are going to be some things that a programmer struggled to get working the first time, that they had to work around, or that was simply unintuitive. These should be commented. Generally I’ve found uncommented code bases to be thrown together haphazardly and to be of lower quality. Same with those that only trivially leave comment breadcrumbs about what is being done, duplicating the code itself.
  - bravetraveler 3y ago
    "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.
    - bsder 3y ago
      > "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.
      - Groxx 3y ago
        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()
      - 3y ago
- IshKebab 3y ago
  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.
  - ckdot2 3y ago
    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-.
    - IshKebab 3y ago
      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.
      - gpderetta 3y ago
        Besides, even function names can go out of date, yet we still give functions meaningful names.
- vezuchyy 3y ago
  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.
  - ShadowBanThis01 3y ago
    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.
    - tormeh 3y ago
      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.
      - ShadowBanThis01 3y ago
        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.
        cerved 3y ago
        If that's the case, you have bigger problems than documentation
        ShadowBanThis01 3y ago
        Like what?
- smrtinsert 3y ago
  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.
- fx1994 3y ago
  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.
- throwaway14356 3y ago
  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.
- furyofantares 3y ago
  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.
- hakunin 3y ago
  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 https://max.engineer/maintainable-code
  - ikekkdcjkfke 3y ago
    If the code doesn't speak for itself...
    - hakunin 3y ago
      …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.
      - someweirdperson 3y ago
        And those meaningful relevant comments will be invisible in between those useless comments that were added to satisfy some tool that counts them.
  - josephg 3y ago
    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.
- gen220 3y ago
  If you're curious to read a well-earned take on comments: http://antirez.com/news/124 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.
jacobsenscott 3y ago
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.
- jacobsenscott 3y ago
  [flagged]
- chinchilla2020 3y ago
  you've never seen a useful comment?
  - jacobsenscott 3y ago
    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.
deleted 3y ago
[deleted]
tremon 3y ago
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.
- balaji1 3y ago
  that's *** brilliant I @#@#@ know that feeling
- taneq 3y ago
  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.
slowmovintarget 3y ago
That assumes that most comments contain cursing.
- comfypotato 3y ago
  No it doesn’t. If any more than 0% of comments contain profanity, then on average code with more profanity will be better.
  - 22c 3y ago
    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.
    - midoridensha 3y ago
      >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.).
tessierashpool 3y ago
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.
- 0cf8612b2e1e 3y ago
  My favorite infamous example being the MPV C locale commit: https://github.com/mpv-player/mpv/commit/1e70e82baa9193f6f027338b0fab0f5078971fbe https://github.com/mpv-player/mpv/commit/1e70e82baa9193f6f02... You can really feel the author's rage at the state of the world.
  - classified 3y ago
    That's a great rant, and not unjustified. I feel with the author.
midoridensha 3y ago
>...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.
- briantakita 3y ago
  > 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 https://news.ycombinator.com/item?id=36626018 for pointing this out.
jancsika 3y ago
> 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.
- darkerside 3y ago
  By the time you are swearing in your comments, I'm pretty sure you know you're cornered
- matheusmoreira 3y ago
  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.
  - 9dev 3y ago
    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.
    - matheusmoreira 3y ago
      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.
deleted 3y ago
[deleted]
Mathnerd314 3y ago
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 https://cme.h-its.org/exelixis/pubs/JanThesis.pdf
Brian_K_White 3y ago
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?

mr_00ff00 3y ago

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.

almet 3y ago
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.
- brazzledazzle 3y ago
  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.
makeworld 3y ago
Wow, that seems strange to me. Seems like the policy should be to make comments when needed, and keep them up to date.
paxys 3y ago
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..
- jacobsenscott 3y ago
  Even better, lets triple the work and require UML diagrams, comments, and code to all be in sync at all times!
  - dylan604 3y ago
    you left out keeping the docs in sync as well
  - chinchilla2020 3y ago
    don't forget the random google sheet that the project manager wants to keep updated
- ckdot2 3y ago
  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-.
  - didntcheck 3y ago
    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
flatline 3y ago
It really depends on the comments. Best practice is to comment “why” something was done, not “what” is being done, or “how”. Every programmer can read code, most code should be pretty self-explanatory. But in any sufficiently complex routine, there are going to be some things that a programmer struggled to get working the first time, that they had to work around, or that was simply unintuitive. These should be commented. Generally I’ve found uncommented code bases to be thrown together haphazardly and to be of lower quality. Same with those that only trivially leave comment breadcrumbs about what is being done, duplicating the code itself.
- bravetraveler 3y ago
  "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.
  - bsder 3y ago
    > "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.
    - Groxx 3y ago
      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()
    - 3y ago
IshKebab 3y ago
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.
- ckdot2 3y ago
  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-.
  - IshKebab 3y ago
    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.
    - gpderetta 3y ago
      Besides, even function names can go out of date, yet we still give functions meaningful names.
vezuchyy 3y ago
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.
- ShadowBanThis01 3y ago
  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.
  - tormeh 3y ago
    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.
    - ShadowBanThis01 3y ago
      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.
      - cerved 3y ago
        If that's the case, you have bigger problems than documentation
        ShadowBanThis01 3y ago
        Like what?
smrtinsert 3y ago
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.
fx1994 3y ago
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.
throwaway14356 3y ago
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.
furyofantares 3y ago
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.
hakunin 3y ago
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 https://max.engineer/maintainable-code
- ikekkdcjkfke 3y ago
  If the code doesn't speak for itself...
  - hakunin 3y ago
    …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.
    - someweirdperson 3y ago
      And those meaningful relevant comments will be invisible in between those useless comments that were added to satisfy some tool that counts them.
- josephg 3y ago
  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.
gen220 3y ago
If you're curious to read a well-earned take on comments: http://antirez.com/news/124 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.

jacobsenscott 3y ago

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.

jacobsenscott 3y ago
[flagged]
chinchilla2020 3y ago
you've never seen a useful comment?
- jacobsenscott 3y ago
  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.

deleted 3y ago

[deleted]

tremon 3y ago

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.

balaji1 3y ago
that's *** brilliant I @#@#@ know that feeling
taneq 3y ago
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.

slowmovintarget 3y ago

That assumes that most comments contain cursing.

comfypotato 3y ago
No it doesn’t. If any more than 0% of comments contain profanity, then on average code with more profanity will be better.
- 22c 3y ago
  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.
  - midoridensha 3y ago
    >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.).

tessierashpool 3y ago

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.

0cf8612b2e1e 3y ago
My favorite infamous example being the MPV C locale commit: https://github.com/mpv-player/mpv/commit/1e70e82baa9193f6f027338b0fab0f5078971fbe https://github.com/mpv-player/mpv/commit/1e70e82baa9193f6f02... You can really feel the author's rage at the state of the world.
- classified 3y ago
  That's a great rant, and not unjustified. I feel with the author.

midoridensha 3y ago

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

briantakita 3y ago
> 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 https://news.ycombinator.com/item?id=36626018 for pointing this out.

jancsika 3y ago

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

darkerside 3y ago
By the time you are swearing in your comments, I'm pretty sure you know you're cornered
matheusmoreira 3y ago
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.
- 9dev 3y ago
  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.
  - matheusmoreira 3y ago
    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.

deleted 3y ago

[deleted]

Mathnerd314 3y ago

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 https://cme.h-its.org/exelixis/pubs/JanThesis.pdf

Brian_K_White 3y ago

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?