6 ms·

If this study is to be believed. Citation-> https://cacm.acm.org/magazines/2017/10/221326-a-large-scale-study-of-programming-languages-and-code-quality-in-githu

If this study is to be believed. Citation-> https://cacm.acm.org/magazines/2017/10/221326-a-large-scale-study-of-programming-languages-and-code-quality-in-github/fulltext https://cacm.acm.org/magazines/2017/10/221326-a-large-scale-... The 5 programming languages with the least amount of bugs are: Haskell Ada Scala Rust *Drum roll please* Ruby Ruby is nothing like the other languages above in design, but that community has fantastic conventions around code clarity, code quality, testing, continuous integration, etc. Comments are for things like, `Todos`, Noting a specific algorithm, maybe a link to a white paper, noting a violation of a convention for speed, security, or some other performance reason. Comments are for things that are __impossible__ to tell from the code.

otikik 4y ago
Agree with most of what you said, except on the __impossible__ part. You can tell everything with code, given enough time and resources. Nothing is "impossible". But there's a point where you hit diminishing returns. It's about efficiency. Other devs, or your future self, will have to time trying to build the same "castle in your head" as you did. Can a comment shorten that time? If a one-line comment saves 15 minutes of investigation in aggregate, that's a no-brainer. You should add it. Conversely, a line that says "add 5 to x" is just wasting everyone's time. As a general rule, once I have finally understood a particularly hairy piece of code, I don't want to do it again in 6 months. I have even done ASCII diagrams in the comments explaining how a particularly hairy piece of code worked, when I hated it enough.
- jofer 4y ago
  ASCII diagram comments are surprisingly common in scientific computing, FWIW. It's not so much that it's always hairy code, more that it helps to add some visualizations of what's going on. Math vs intuitive understanding are often very different things. It's something I wish was more common than it is. Sometimes you really want that ASCII pseudo graph explaining how minimizing this thing relates to that other thing that we actually care about. Taken a step further, I really wish we had better systems for managing this type of information alongside a codebase. E.g. the whitepaper, or presentation, or figures, or whatever is often very necessary to understand the code, and ideally it would be under version control and live neatly alongside things. Nicely rendered docs definitely help with this (e.g. latex in comments), but I'm always surprised there aren't more people focusing on this aspect of information management.
- lumb63 4y ago
  In my experience, one man’s “waste of time” is another man’s castle-in-the-head-building-time-saver. At my current company, if I have reasonable, self explanatory code, such as a function with the signature “read_page(page_num: u32) -> PageData”, they’ll gather it reads a page with the given page number and extracts the data. At my last company, if I wrote the same code, I’d receive a comment on my PR complaining I did not document it will enough. I would then add a comment that somehow only I was able to detect was snarkily written, something like “// reads the given page number and returns its data” and they would be happy as clams. I always assumed that behavior was dogmatic until, over many PRs, multiple members of the team commented that if I commented my code, it would be much easier to read. And comments of the above quality assuaged them.
  - layer8 4y ago
    What I would miss, in the above, is information about: - where the page is being read from - what page numbers the function accepts - what happens if an invalid page number is specified (or if that’s deliberately undefined, stating that fact) - other possible error conditions, if any (I’ll assume that PageData already documents what “page” refers to in that context, because for me it’s not “self explanatory” just from the function signature you provided.)
- still_grokking 4y ago
  > You can tell everything with code, given enough time and resources. That's just not true. There are infinite many ways to write the exact same thing. Your code can never say why it's like it is, why this approach was chosen and not another. > […] the comments explaining how a particularly hairy piece of code worked […] This kind of comments are the bad ones actually. Your code should be clear enough that it's easy to see how it works and what is happening. The rule is actually very simple, and I don't get it why so many people have issues with following it. "Code says what and how, comments say why."
  - TedDoesntTalk 4y ago
    > The rule is actually very simple Why does there have to be rules about when to comment? I comment frequently about whatever the hell I want. Don’t like it? Then don’t read the comments. Very simple, just like your rule.
    - still_grokking 4y ago
      Useless comments are like useless code: They create an unnecessary (and therefore costly) maintenance burden. If you think you're the smartest person on the planet so "rules" (or better said best practices) don't apply to anything you do I hope nobody ever needs to collaborate with you. All the "rules" are there for a reason! No, you're not free do to whatever you like in a professional setting. For example when you're operating machines you need to follow safety regulations. Otherwise you could even end up in jail quite quickly.
      - TedDoesntTalk 4y ago
        > All the "rules" are there for a reason! Except in this case, you've made up the rule. It is not an axiomatic rule like gravity. I want different rules. So unless we work together, your rules don't apply to me.
  - otikik 4y ago
    > There are infinite many ways to write the exact same thing. I agree with that. I don't think that makes things impossible. Only more difficult. > Your code can never say why it's like it is, why this approach was chosen and not another. If the why is important, given enough time and resources, someone will eventually complain that something is not working and someone will be tasked to "fix it". It may take them weeks, but they will eventually figure out the why. > Code says what and how, comments say why. If we are considering only quality vs quality, I agree. But there's also quantity. When the how is complicated enough, it is indistinguishable from a why. You will hear the reviewers ask outloud: "But WHY is this done this way?". Even if the problem is merely algorithmic/technical and the code is doing exactly what it's supposed to do. Then you have two options: spend a potentially significant time refactoring things (which is always the right choice, given enough time and resources) or spend 10 minutes writing a comment with what you learned, and moving on to the next problem.
jaywalk 4y ago
I wish I could get this point across to my team. They will happily write: db.insert(record); // save the record to the database But when they write some crazy off-the-wall code (that's usually because they didn't understand the proper way to do something) I have to check the logs to see who wrote it and ask them why. Just the other day I was debugging an application that had a 6 second sleep at the end of the main() function. I just figured it was some dumb thing left in for debugging and deleted it, because there's no good reason to do that. The next day, the dev who put it in messaged me and said he put it there because the application was exiting before it had logged it's completion to our logging system. So I explained that the proper way to do this is to flush the log, not just hang the application for 6 seconds so that the last messages just happen to go through. If there was a comment explaining why there was a 6 second sleep, I could have just fixed it and educated the developer without causing any grief.
- weatherlight 4y ago
  thats a legit case of, "its impossible to gleam that fact from the code and the code alone." (although I would have left that as a comment for the reviewer in the PR) so if theres a conversation around that decision, it would have been captured there.)
  - still_grokking 4y ago
    The discussion in the PR does not help the next guy… All why answers belong into the code, as comments.
- layer8 4y ago
  > I just figured it was some dumb thing left in for debugging and deleted it, because there's no good reason to do that. Look up Chesterton’s Fence. :) (I made similar errors more than once.)
  - hbrn 4y ago
    You should be very careful applying Chesterton’s Fence to software engineering. Oftentimes the knowledge why fence exists is more valuable than the fence itself. And the best way to (re-)obtain this knowledge is to remove the fence and see what breaks. I've seen people get stuck for months being afraid to change a complex piece of code because nobody understands how it works anymore. The best course of action was to admit that knowledge is lost forever and the fastest way to gain it again is to repeat past mistakes. Of course, don't do this if your software is responsible for landing airplanes. But most of us are not landing airplanes here.
tln 4y ago
Interesting paper, thanks for posting. The paper goes on to say: > One should take care not to overestimate the impact of language on defects. While the observed relationships are statistically significant, the effects are quite small. Analysis of deviance reveals that language accounts for less than 1% of the total explained deviance
j45 4y ago
Comments are critical at creating beginners to the code base, something rarely the expert class think about accelerating. For my code? I agree Code for others to participate in? The simplest possible way for the greatest number of developers to understand as quickly as possible. Not about my best practice or preference but for the greater good. Coding standards for the elite devs are only so effective at growing that growing quick enough.
- layer8 4y ago
  The expert will be helped as well when coming back to the code after a few months.
  - j45 4y ago
    100%. Comments are a critical way to more quickly re-grok the mental model of what's going on for your future self as well. I think there was a post in the past few weeks about a single developer who maintained hundreds of his own tools, and for him it came down to process and documentation first so it was easy to come back to months or years later.
jhhh 4y ago
Where are Ada and Rust mentioned in that link? The top listed down to Ruby in that link by general failure seem to be: Scala, Perl, Clojure/PHP (tied), Haskell/Go (tied), TypeScript, Ruby.
aardvark179 4y ago
The Ruby community has a very good culture of testing application and framework code, but in my experience is quite poor at properly specifying behaviour or writing truly robust code. Many functions in the standard library behave subtly differently from there documentation or have behaviour that is not documented but depended on by applications, and I’ve certainly seen lots of concurrency bugs in both code and tests because the GVL makes it hard to provoke the worst case behaviour. The unit tests are really useful for Ruby language implementations because they help give us confidence we’re replicating all the required behaviour, but from that point of view I wish the underlying things were better specified so those tests weren’t quite so necessary. Don’t get me wrong. I love Ruby as a language and loved working on TruffleRuby, but I don’t think the community should be too smug about code quality and testing.

otikik 4y ago

Agree with most of what you said, except on the __impossible__ part. You can tell everything with code, given enough time and resources. Nothing is "impossible". But there's a point where you hit diminishing returns. It's about efficiency. Other devs, or your future self, will have to time trying to build the same "castle in your head" as you did. Can a comment shorten that time? If a one-line comment saves 15 minutes of investigation in aggregate, that's a no-brainer. You should add it. Conversely, a line that says "add 5 to x" is just wasting everyone's time. As a general rule, once I have finally understood a particularly hairy piece of code, I don't want to do it again in 6 months. I have even done ASCII diagrams in the comments explaining how a particularly hairy piece of code worked, when I hated it enough.

jofer 4y ago
ASCII diagram comments are surprisingly common in scientific computing, FWIW. It's not so much that it's always hairy code, more that it helps to add some visualizations of what's going on. Math vs intuitive understanding are often very different things. It's something I wish was more common than it is. Sometimes you really want that ASCII pseudo graph explaining how minimizing this thing relates to that other thing that we actually care about. Taken a step further, I really wish we had better systems for managing this type of information alongside a codebase. E.g. the whitepaper, or presentation, or figures, or whatever is often very necessary to understand the code, and ideally it would be under version control and live neatly alongside things. Nicely rendered docs definitely help with this (e.g. latex in comments), but I'm always surprised there aren't more people focusing on this aspect of information management.
lumb63 4y ago
In my experience, one man’s “waste of time” is another man’s castle-in-the-head-building-time-saver. At my current company, if I have reasonable, self explanatory code, such as a function with the signature “read_page(page_num: u32) -> PageData”, they’ll gather it reads a page with the given page number and extracts the data. At my last company, if I wrote the same code, I’d receive a comment on my PR complaining I did not document it will enough. I would then add a comment that somehow only I was able to detect was snarkily written, something like “// reads the given page number and returns its data” and they would be happy as clams. I always assumed that behavior was dogmatic until, over many PRs, multiple members of the team commented that if I commented my code, it would be much easier to read. And comments of the above quality assuaged them.
- layer8 4y ago
  What I would miss, in the above, is information about: - where the page is being read from - what page numbers the function accepts - what happens if an invalid page number is specified (or if that’s deliberately undefined, stating that fact) - other possible error conditions, if any (I’ll assume that PageData already documents what “page” refers to in that context, because for me it’s not “self explanatory” just from the function signature you provided.)
still_grokking 4y ago
> You can tell everything with code, given enough time and resources. That's just not true. There are infinite many ways to write the exact same thing. Your code can never say why it's like it is, why this approach was chosen and not another. > […] the comments explaining how a particularly hairy piece of code worked […] This kind of comments are the bad ones actually. Your code should be clear enough that it's easy to see how it works and what is happening. The rule is actually very simple, and I don't get it why so many people have issues with following it. "Code says what and how, comments say why."
- TedDoesntTalk 4y ago
  > The rule is actually very simple Why does there have to be rules about when to comment? I comment frequently about whatever the hell I want. Don’t like it? Then don’t read the comments. Very simple, just like your rule.
  - still_grokking 4y ago
    Useless comments are like useless code: They create an unnecessary (and therefore costly) maintenance burden. If you think you're the smartest person on the planet so "rules" (or better said best practices) don't apply to anything you do I hope nobody ever needs to collaborate with you. All the "rules" are there for a reason! No, you're not free do to whatever you like in a professional setting. For example when you're operating machines you need to follow safety regulations. Otherwise you could even end up in jail quite quickly.
    - TedDoesntTalk 4y ago
      > All the "rules" are there for a reason! Except in this case, you've made up the rule. It is not an axiomatic rule like gravity. I want different rules. So unless we work together, your rules don't apply to me.
- otikik 4y ago
  > There are infinite many ways to write the exact same thing. I agree with that. I don't think that makes things impossible. Only more difficult. > Your code can never say why it's like it is, why this approach was chosen and not another. If the why is important, given enough time and resources, someone will eventually complain that something is not working and someone will be tasked to "fix it". It may take them weeks, but they will eventually figure out the why. > Code says what and how, comments say why. If we are considering only quality vs quality, I agree. But there's also quantity. When the how is complicated enough, it is indistinguishable from a why. You will hear the reviewers ask outloud: "But WHY is this done this way?". Even if the problem is merely algorithmic/technical and the code is doing exactly what it's supposed to do. Then you have two options: spend a potentially significant time refactoring things (which is always the right choice, given enough time and resources) or spend 10 minutes writing a comment with what you learned, and moving on to the next problem.

jaywalk 4y ago

I wish I could get this point across to my team. They will happily write: db.insert(record); // save the record to the database But when they write some crazy off-the-wall code (that's usually because they didn't understand the proper way to do something) I have to check the logs to see who wrote it and ask them why. Just the other day I was debugging an application that had a 6 second sleep at the end of the main() function. I just figured it was some dumb thing left in for debugging and deleted it, because there's no good reason to do that. The next day, the dev who put it in messaged me and said he put it there because the application was exiting before it had logged it's completion to our logging system. So I explained that the proper way to do this is to flush the log, not just hang the application for 6 seconds so that the last messages just happen to go through. If there was a comment explaining why there was a 6 second sleep, I could have just fixed it and educated the developer without causing any grief.

weatherlight 4y ago
thats a legit case of, "its impossible to gleam that fact from the code and the code alone." (although I would have left that as a comment for the reviewer in the PR) so if theres a conversation around that decision, it would have been captured there.)
- still_grokking 4y ago
  The discussion in the PR does not help the next guy… All why answers belong into the code, as comments.
layer8 4y ago
> I just figured it was some dumb thing left in for debugging and deleted it, because there's no good reason to do that. Look up Chesterton’s Fence. :) (I made similar errors more than once.)
- hbrn 4y ago
  You should be very careful applying Chesterton’s Fence to software engineering. Oftentimes the knowledge why fence exists is more valuable than the fence itself. And the best way to (re-)obtain this knowledge is to remove the fence and see what breaks. I've seen people get stuck for months being afraid to change a complex piece of code because nobody understands how it works anymore. The best course of action was to admit that knowledge is lost forever and the fastest way to gain it again is to repeat past mistakes. Of course, don't do this if your software is responsible for landing airplanes. But most of us are not landing airplanes here.

tln 4y ago

Interesting paper, thanks for posting. The paper goes on to say: > One should take care not to overestimate the impact of language on defects. While the observed relationships are statistically significant, the effects are quite small. Analysis of deviance reveals that language accounts for less than 1% of the total explained deviance

j45 4y ago

Comments are critical at creating beginners to the code base, something rarely the expert class think about accelerating. For my code? I agree Code for others to participate in? The simplest possible way for the greatest number of developers to understand as quickly as possible. Not about my best practice or preference but for the greater good. Coding standards for the elite devs are only so effective at growing that growing quick enough.

layer8 4y ago
The expert will be helped as well when coming back to the code after a few months.
- j45 4y ago
  100%. Comments are a critical way to more quickly re-grok the mental model of what's going on for your future self as well. I think there was a post in the past few weeks about a single developer who maintained hundreds of his own tools, and for him it came down to process and documentation first so it was easy to come back to months or years later.

jhhh 4y ago

Where are Ada and Rust mentioned in that link? The top listed down to Ruby in that link by general failure seem to be: Scala, Perl, Clojure/PHP (tied), Haskell/Go (tied), TypeScript, Ruby.

aardvark179 4y ago

The Ruby community has a very good culture of testing application and framework code, but in my experience is quite poor at properly specifying behaviour or writing truly robust code. Many functions in the standard library behave subtly differently from there documentation or have behaviour that is not documented but depended on by applications, and I’ve certainly seen lots of concurrency bugs in both code and tests because the GVL makes it hard to provoke the worst case behaviour. The unit tests are really useful for Ruby language implementations because they help give us confidence we’re replicating all the required behaviour, but from that point of view I wish the underlying things were better specified so those tests weren’t quite so necessary. Don’t get me wrong. I love Ruby as a language and loved working on TruffleRuby, but I don’t think the community should be too smug about code quality and testing.