11 ms·

> Oh, and the original author doesn't work here anymore so no one's here to explain the original code's intent. To be fair, even if I still work there I don't

> Oh, and the original author doesn't work here anymore so no one's here to explain the original code's intent. To be fair, even if I still work there I don't know that I'm going to be of much help 6 months later other than a "oh yeah, I remember that had some weird business requirements"

throwup238 2y ago
Thank god we’re held to such low standards. Every time I’ve worked in a field like pharmaceuticals or manufacturing, the documentation burden felt overwhelming by comparison and a shrug six months later would never fly.
- Yiin 2y ago
  there is difference between building a dashboard for internal systems and tech that if failed can kill people
  - throwup238 2y ago
    Most software work in pharma and manufacturing is still CRUD, they just have cultures of rigorous documentation that permeates the industry even when it's low value. Documenting every little change made sense when I was programming the robotics for a genetic diagnostics pipeline, not so much when I had to write a one pager justifying a one line fix to the parser for the configuration format or updating some LIMS dependency to fix a vulnerability in an internal tool that's not even open to the internet.
  - Mikhail_Edoshin 2y ago
    Well, a hand watch or a chair cannot kill people, but the manufacturing documentation for them will be very precise. Software development is not engineering because it is still relatively young and immature field. There is a joke where a mathematician, a physicist and a engineer are given a little red rubber ball and asked to find its volume. The mathematician measures the diameter and computes, the physicist immerses the ball into water and sees how much was displaced, and an the engineer looks it up in his "Little red rubber balls" reference. Software development does not yet have anything that may even potentially grow into such a reference. If we decide to write it we would not even know where to start. We have mathematicians who write computer science papers; or physicists who test programs; standup comedians, philosophers, everyone. But not engineers.
    - ozim 2y ago
      Difference is that code is the documentation and design. That is problem where people don’t understand that point. Runtime and running application is the chair. Code is design how to make “chair” run on computer. I say in software development we are years ahead when it comes to handling complexity of documentation with GIT and CI/CD practices, code reviews and QA coverage with unit testing of the designs and general testing. So I do not agree that software development is immature field. There are immature projects and companies cut corners much more than on physical products because it is much easier to fix software later. But in terms of practices we are way ahead.
      - dambi0 2y ago
        Isn’t this similar to saying the valves and vessels of a chemical processing system is the design and documentation of the overall process? I know that it’s frequently reposted but Peter Naur’s Programming as Theory Building is always worth a reread. The code doesn’t tell us why decisions were made, what constraints were considered or what things were ruled out
    - deleted 2y ago
      [deleted]
  - larodi 2y ago
    The word code comes from Latin coudex which seems mean - to hack a tree. Are we then not mere lumberjacks with the beards and beer and all :)))
- mnau 2y ago
  We are not engineers. We are craftsmen, instead of working with wood, we work with code. What most customers want is an equivalent of "I need a chair, it should look roughly like this." If they want blueprints and documentation (e.g. maximum possible load and other limits), we can supply (and do supply, e.g. in pharma or medicine), but it will cost them quite a lot more. By the order of magnitude. Most customers prefer cobbled up solution that is cheap and works. That's on them. Edit: It is called waterfall. There is nothing inherently wrong with it, except customers didn't like the time it took to implement a change. And they want changes all the time.
  - namaria 2y ago
    > We are not engineers. We are craftsmen Same difference. Both appellations invoke some sort of idealized professional standards and the conversation is about failing these standards not upholding them. We're clearly very short of deserving a title that carries any sort of professional pride in it. We are making a huge mess of the world building systems that hijack attention for profit and generate numerous opportunities for bad agents in the form of security shortfalls or opportunities to exploit people using machines and code. If we had any sort of pride of craft or professional standards we wouldn't be pumping out the bug ridden mess that software's become and trying to figure out why in this conversation.
    - alternatex 2y ago
      That is quite a cynical take. A lot of us take pride in our work and actively avoid companies that produce software that is detrimental to society.
      - namaria 2y ago
        It is cynical but it is also a generalization better supported by the evidence than "we're craftsmen" or "we're engineers". If you can say "I'm a craftsman" or "I'm an engineer" all the power to you. Sadly I don't think we can say that in the collective form.
- rcxdude 2y ago
  OTOH, the level of documentation you get for free from source control would be a godsend in other contexts: the majority of the documentation you see in other processes is just to get an idea of what changed when and why.
stouset 2y ago
Might I recommend writing those weird business requirements down as comments instead of just hoping someone will guess them six months down the line?
- mnsc 2y ago
  So even if comments are flawlessly updated they are not a silver bullet. Not everyone are good at explaining confusing concepts in plain English so worst case you have confusing code and a comment that is 90% accurate but describe one detail in a way that doesn't really match what the code says. This will make you question if you have understood what the code does and it will take time and effort to convince yourself that code is in fact deterministic and unsurprising. (but most often the comment is is just not updated or updated along with the code but without full understanding, which is what caused the bug that is the reason you are looking at the code in question)
  - rtpg 2y ago
    An outdated comment is still a datapoint! Including if the comment was wrong when it was first written! We live in a world with version history, repositories with change requests, communications… code comments are a part of that ecosystem. A comment that is outright incorrect at inception is still valuable even if it is at least an attempt by the writer to describe their internal understanding of things.
    - more-coffee 2y ago
      This. I have argued with plenty of developers on why comments are useful, and the counter arguments are always the same. I believe it boils down to a lack of foresight. At some point in time, someone is going to revisit your code, and even just a small `// Sorry this is awful, we have to X but this was difficult because of Y` will go a long way. While I (try to) have very fluid opinions in all aspects of programming, the usefulness of comments is not something I (think!) I'll ever budge on. :)
      - 2y ago

throwup238 2y ago

Thank god we’re held to such low standards. Every time I’ve worked in a field like pharmaceuticals or manufacturing, the documentation burden felt overwhelming by comparison and a shrug six months later would never fly.

Yiin 2y ago
there is difference between building a dashboard for internal systems and tech that if failed can kill people
- throwup238 2y ago
  Most software work in pharma and manufacturing is still CRUD, they just have cultures of rigorous documentation that permeates the industry even when it's low value. Documenting every little change made sense when I was programming the robotics for a genetic diagnostics pipeline, not so much when I had to write a one pager justifying a one line fix to the parser for the configuration format or updating some LIMS dependency to fix a vulnerability in an internal tool that's not even open to the internet.
- Mikhail_Edoshin 2y ago
  Well, a hand watch or a chair cannot kill people, but the manufacturing documentation for them will be very precise. Software development is not engineering because it is still relatively young and immature field. There is a joke where a mathematician, a physicist and a engineer are given a little red rubber ball and asked to find its volume. The mathematician measures the diameter and computes, the physicist immerses the ball into water and sees how much was displaced, and an the engineer looks it up in his "Little red rubber balls" reference. Software development does not yet have anything that may even potentially grow into such a reference. If we decide to write it we would not even know where to start. We have mathematicians who write computer science papers; or physicists who test programs; standup comedians, philosophers, everyone. But not engineers.
  - ozim 2y ago
    Difference is that code is the documentation and design. That is problem where people don’t understand that point. Runtime and running application is the chair. Code is design how to make “chair” run on computer. I say in software development we are years ahead when it comes to handling complexity of documentation with GIT and CI/CD practices, code reviews and QA coverage with unit testing of the designs and general testing. So I do not agree that software development is immature field. There are immature projects and companies cut corners much more than on physical products because it is much easier to fix software later. But in terms of practices we are way ahead.
    - dambi0 2y ago
      Isn’t this similar to saying the valves and vessels of a chemical processing system is the design and documentation of the overall process? I know that it’s frequently reposted but Peter Naur’s Programming as Theory Building is always worth a reread. The code doesn’t tell us why decisions were made, what constraints were considered or what things were ruled out
  - deleted 2y ago
    [deleted]
- larodi 2y ago
  The word code comes from Latin coudex which seems mean - to hack a tree. Are we then not mere lumberjacks with the beards and beer and all :)))
mnau 2y ago
We are not engineers. We are craftsmen, instead of working with wood, we work with code. What most customers want is an equivalent of "I need a chair, it should look roughly like this." If they want blueprints and documentation (e.g. maximum possible load and other limits), we can supply (and do supply, e.g. in pharma or medicine), but it will cost them quite a lot more. By the order of magnitude. Most customers prefer cobbled up solution that is cheap and works. That's on them. Edit: It is called waterfall. There is nothing inherently wrong with it, except customers didn't like the time it took to implement a change. And they want changes all the time.
- namaria 2y ago
  > We are not engineers. We are craftsmen Same difference. Both appellations invoke some sort of idealized professional standards and the conversation is about failing these standards not upholding them. We're clearly very short of deserving a title that carries any sort of professional pride in it. We are making a huge mess of the world building systems that hijack attention for profit and generate numerous opportunities for bad agents in the form of security shortfalls or opportunities to exploit people using machines and code. If we had any sort of pride of craft or professional standards we wouldn't be pumping out the bug ridden mess that software's become and trying to figure out why in this conversation.
  - alternatex 2y ago
    That is quite a cynical take. A lot of us take pride in our work and actively avoid companies that produce software that is detrimental to society.
    - namaria 2y ago
      It is cynical but it is also a generalization better supported by the evidence than "we're craftsmen" or "we're engineers". If you can say "I'm a craftsman" or "I'm an engineer" all the power to you. Sadly I don't think we can say that in the collective form.
rcxdude 2y ago
OTOH, the level of documentation you get for free from source control would be a godsend in other contexts: the majority of the documentation you see in other processes is just to get an idea of what changed when and why.

stouset 2y ago

Might I recommend writing those weird business requirements down as comments instead of just hoping someone will guess them six months down the line?

mnsc 2y ago
So even if comments are flawlessly updated they are not a silver bullet. Not everyone are good at explaining confusing concepts in plain English so worst case you have confusing code and a comment that is 90% accurate but describe one detail in a way that doesn't really match what the code says. This will make you question if you have understood what the code does and it will take time and effort to convince yourself that code is in fact deterministic and unsurprising. (but most often the comment is is just not updated or updated along with the code but without full understanding, which is what caused the bug that is the reason you are looking at the code in question)
- rtpg 2y ago
  An outdated comment is still a datapoint! Including if the comment was wrong when it was first written! We live in a world with version history, repositories with change requests, communications… code comments are a part of that ecosystem. A comment that is outright incorrect at inception is still valuable even if it is at least an attempt by the writer to describe their internal understanding of things.
  - more-coffee 2y ago
    This. I have argued with plenty of developers on why comments are useful, and the counter arguments are always the same. I believe it boils down to a lack of foresight. At some point in time, someone is going to revisit your code, and even just a small `// Sorry this is awful, we have to X but this was difficult because of Y` will go a long way. While I (try to) have very fluid opinions in all aspects of programming, the usefulness of comments is not something I (think!) I'll ever budge on. :)
    - 2y ago