4 ms·

Having worked in multiple environments with differing code quality standards, it's pretty apparent how both "minimum and yeet" and "completion or bust" fail. "

by lumost 3y ago

Having worked in multiple environments with differing code quality standards, it's pretty apparent how both "minimum and yeet" and "completion or bust" fail. "Minimum and yeet" works surprisingly well if you have unsolvable debates on customer value, options to yank the feature if it sucks, and generally competent engineers. If you are really good at yanking the feature when it sucks - you may even be able to get away with incompetent engineers. However if you repeat this cycle on the same code base 100x over, every feature gets harder. Eventually you hit a point where no one really knows how to do anything anymore as a feature that used to take 2 weeks now takes 8 months. "Completion or bust" works really well when you can't take a feature back... ever. However the definition of completion tends to grow over time. I've seen launch checklists which amounted to 6 month projects on their own (for both good and bad reasons). Sometimes completion becomes an excuse for architectural astronauts to enforce a change resistant paradigm on the code, eliminating any gains from completionism. Other times, the engineers and managers become convinced that any change will take N months and start ignoring everything that doesn't look like it will provide N months of value. In an ideal world, I'd love to see organizations better adapt their standards to the needs of individual teams or invest in tooling which makes it "cheap" to do the right thing. However this is not easy to pull off.

t-writescode 3y ago
I love this whole post! Small add: "generally competent engineers" can sometimes (almost) inline most of the code completeness details for cheap, reducing their cost greatly. Writing documentation is always a time sink, though, in my experience. Or maybe I'm just not good at it :P It's usually an additional day of work overall, though.
- tracker1 3y ago
  Depends on what you're doing... For a developer focused documentation, I often will write a bit of the documentation up front as a project is getting setup with the intent on how it should work locally (or per developer). Then fill in details as each part gets more flushed out. Same for library APIs, command-line scripts/tools etc. For end-user products with a user interface, less so as it comes down to being flexible... similar with dashboards, as a developer I often don't know what is wanted up front... when something is asked for and you learn the domain more, it can come together easier. Larger projects with a front end component and many developers, nearly have to forget it at the dev level.
- Spellinator 3y ago
  Writing docs, especially detailed and complete, can really save you in the long run. Plus the people that come after you will greatly appreciate your efforts.
- huganabaga 3y ago
  > Writing documentation is always a time sink, though, in my experience. Or maybe I'm just not good at it :P It's usually an additional day of work overall, though. And it saves you days and days of re-discovering truths about your code weeks/months/years down the line. Sometimes those rediscovered facts are not even true which will come bite you big time. Integrate your documentation with your testing. That makes it easier to create and maintain. You don't have comprehensive automatic tests? Then that's your problem right there.
  - t-writescode 3y ago
    There are several forms of documentation: * comments in code * team-based comments * project design docs * knowledge-base articles for handling on-call rotation around feature * how-to guides for customers Each of these has a different cost and a different direct/external usefulness. I absolutely believe in good documentation and I absolutely believe that it's valuable. It does not negate the extra cost of including these forms of documentation - especially the "not-in-code" documentation.
    - huganabaga 3y ago
      Of course they "cost". But the issue is the mindset that they are "extra". They are not. They are an integral part to professional software engineering. You can't take them away without moving from a professional craft into some hobby hack. When developing medicine you wouldn't consider safety studies as "extra". When you fly an airplane then the take off checklist is not "extra". Arguing that automated test suites or documentation are just "extra" on top of making software and could be skipped is similar to arguing that you could fly a plane without any checklists or releasing medicine to the public without evaluating its safety. That's just unprofessional nonsense.
reidjs 3y ago
What do you mean by this? > In an ideal world, I'd love to see organizations better adapt their standards to the needs of individual teams or invest in tooling which makes it "cheap" to do the right thing. However this is not easy to pull off. What does that look like in practice?
- ssrc 3y ago
  For the tooling part, I suppose it's something like a "golden path"[1] where you have predefined templates from which the developers may choose the most appropriate for their problem. [1] https://cloud.redhat.com/blog/designing-golden-paths https://cloud.redhat.com/blog/designing-golden-paths
huganabaga 3y ago
>invest in tooling which makes it "cheap" to do the right thing. However this is not easy to pull off. Automated testing FTW. Then you can change and refactor and extend all day, as long as the tests are all green, you are golden.

by lumost 3y ago

t-writescode 3y ago

I love this whole post! Small add: "generally competent engineers" can sometimes (almost) inline most of the code completeness details for cheap, reducing their cost greatly. Writing documentation is always a time sink, though, in my experience. Or maybe I'm just not good at it :P It's usually an additional day of work overall, though.

tracker1 3y ago
Depends on what you're doing... For a developer focused documentation, I often will write a bit of the documentation up front as a project is getting setup with the intent on how it should work locally (or per developer). Then fill in details as each part gets more flushed out. Same for library APIs, command-line scripts/tools etc. For end-user products with a user interface, less so as it comes down to being flexible... similar with dashboards, as a developer I often don't know what is wanted up front... when something is asked for and you learn the domain more, it can come together easier. Larger projects with a front end component and many developers, nearly have to forget it at the dev level.
Spellinator 3y ago
Writing docs, especially detailed and complete, can really save you in the long run. Plus the people that come after you will greatly appreciate your efforts.
huganabaga 3y ago
> Writing documentation is always a time sink, though, in my experience. Or maybe I'm just not good at it :P It's usually an additional day of work overall, though. And it saves you days and days of re-discovering truths about your code weeks/months/years down the line. Sometimes those rediscovered facts are not even true which will come bite you big time. Integrate your documentation with your testing. That makes it easier to create and maintain. You don't have comprehensive automatic tests? Then that's your problem right there.
- t-writescode 3y ago
  There are several forms of documentation: * comments in code * team-based comments * project design docs * knowledge-base articles for handling on-call rotation around feature * how-to guides for customers Each of these has a different cost and a different direct/external usefulness. I absolutely believe in good documentation and I absolutely believe that it's valuable. It does not negate the extra cost of including these forms of documentation - especially the "not-in-code" documentation.
  - huganabaga 3y ago
    Of course they "cost". But the issue is the mindset that they are "extra". They are not. They are an integral part to professional software engineering. You can't take them away without moving from a professional craft into some hobby hack. When developing medicine you wouldn't consider safety studies as "extra". When you fly an airplane then the take off checklist is not "extra". Arguing that automated test suites or documentation are just "extra" on top of making software and could be skipped is similar to arguing that you could fly a plane without any checklists or releasing medicine to the public without evaluating its safety. That's just unprofessional nonsense.

reidjs 3y ago

What do you mean by this? > In an ideal world, I'd love to see organizations better adapt their standards to the needs of individual teams or invest in tooling which makes it "cheap" to do the right thing. However this is not easy to pull off. What does that look like in practice?

ssrc 3y ago
For the tooling part, I suppose it's something like a "golden path"[1] where you have predefined templates from which the developers may choose the most appropriate for their problem. [1] https://cloud.redhat.com/blog/designing-golden-paths https://cloud.redhat.com/blog/designing-golden-paths

huganabaga 3y ago

>invest in tooling which makes it "cheap" to do the right thing. However this is not easy to pull off. Automated testing FTW. Then you can change and refactor and extend all day, as long as the tests are all green, you are golden.