6 ms·

I've handed off a few services I built with minimal oversight or documentation. The receiving teams have been able to make changes without my involvement and ev

I've handed off a few services I built with minimal oversight or documentation. The receiving teams have been able to make changes without my involvement and everyone is happy. I believe the only reason I've been successful in this is because I agonize over simplicity. There are times during the development of any project where one might be tempted to hack around an issue, or commit the ugly code that seems to work. These are the rough edges that inheritors of a codebase use as evidence that a blank slate would be preferable. They're also the bits where the underlying business logic becomes murky. My goal is for the code to be so clear that documentation would feel redundant. This approach of course takes more time and requires that your management trusts you and is willing to compromise on timelines. It's extremely rewarding if you can sell it and deliver.

MrMcCall 2y ago
Documentation is useful, when done well. The code is always the authority, and there are very many ways the correct logic can be constructed. How it is constructed is the difference between good enough and excellent. And getting "compromise on timelines" is a most sublime political art. It requires the combination of both a humble, competent manager and an established, successful engineer worthy of trust. Congratulations on your success on those two varied fronts!
- nosefurhairdo 2y ago
  Thank you! I am indeed very fortunate to have a great manager.
- chrsig 2y ago
  I think it depends on who the documentation is intended for. I often let public facing documentation be the source of truth for expected behavior unless it's infeasible to coerce the system to that behavior. If the latter does occur, the documentation gets updated. If the question is what does the software actually do, then of course the code, toolchain, and runtime are the authority.
  - MrMcCall 2y ago
    Good point. I was only speaking to targeting other developers.
- t43562 2y ago
  It needs to answer the "why" question most IMO. I can read code and see "how" and perhaps guess "what" but the "why" is missing. It also doesn't have to be that detailed - just a one line comment at the top of a file saying why it's there and what for can make an immense difference to the time it takes to understand code. Class comments are great too if they have in them everything that's NOT in a ChatGPT summary :-). i.e. I can paste code into ChatGPT myself to get a summary if I really wanted to so I don't need that - but I need all the things it doesn't tell you which is basically why the class exists and what it's intended for. The lower down the hierarchy it goes the less comments matter IMO.
mjr00 2y ago
I have the same experience, and I agree that simplicity leads to success. The more things software can do, the harder it is to reason about what it's supposed to do. It's very much the IQ bell curve meme: junior developers only solve the problem at hand, mid-level developers build powerful, but complex frameworks which can solve the problem at hand but also potential future problems, and senior "X10" developers only solve the problem at hand. > There are times during the development of any project where one might be tempted to hack around an issue, or commit the ugly code that seems to work. These are the rough edges that inheritors of a codebase use as evidence that a blank slate would be preferable. Yes, one thing I've learned is to never underestimate the power of inertia in a codebase. When adding functionality, 99% of developers will go for the path of least resistance, which is mimicking whatever patterns already exist. To loop back to the article, this is often due to lack of full understanding; the default assumption is that because something is written in a certain way, that it's the best way. This isn't true; it may not even be the correct way! But copying what already exists has an element of safety built into it, without needing to spend the effort to deeply understand existing code (which tends to be developers' least favorite activity). So if you put in an ugly hack, or have a code structure which doesn't make sense, expect that to persist for years, or decades.
- tkiolp4 2y ago
  I don’t think it’s up to the developers only to decide. If we are working in a sprint, if all my manager cares about is “shipping impact”, then I’m not going to spend time on things that won’t benefit me in my performance review. I’ll take the shortcuts. Now, if management knew what we know, sure certainly everyone would benefit from that… but that’s not the real world.
- anal_reactor 2y ago
  > without needing to spend the effort to deeply understand existing code Or, more importantly, explain to others why you're deviating from "standard"
- t43562 2y ago
  Deviating from the "standard" can make it harder for another maintainer to understand what's going on. IMO setting up reasonable patterns for others to follow is part of a good design. I'm not saying that I personally am great at it - it's an ideal! I think you are right though - very non-understandable things tend to persist because nobody wants to touch them.
worik 2y ago
> I've handed off a few services I built with minimal oversight or documentation. The receiving teams have been able to make changes without my involvement and everyone is happy. I struggle to believe this. Perhaps my personal situation, inheriting a 150k line embedded C programme, which started sprouting weird bugs when ported from X86 -> ARM. > minimal oversight or documentation Why? Why do you not have documentation? > I've been successful in this is because I agonize over simplicity I will break this down: "I've been successful in this " I do not believe this statement > I agonize over simplicity I wonder if the subordinates in your organisation who are not allowed to criticise you, wish you had agonised over documentation (I do not know what power you have over the folks who follow you, I am hypothesising it is a lot) Documentation is very hard. It is harder than writing code because there is no parsing of documentation, no demonstration of correctness. Inaccurate, or lazy, documentation can be worse than useless, but no documentation condemns the system to a slow death I wish my fellow computer programmers would stop making excuses for not doing the extremely hard work of documenting what they were thinking they were doing when they (inevitably) did something slightly differnent
- chaps 2y ago
  > Why? Why do you not have documentation? > Documentation is very hard. It is harder than writing code because there is no parsing of documentation, no demonstration of correctness. You answered your own question :)
  - worik 2y ago
    > You answered your own question :) So "do not do the hard parts"? That is very unprofessional
    - golergka 2y ago
      Achieving desired result is professional. And achieving desired result without doing the hard parts is not only professional, but smart and actually kind of awesome.
jack_h 2y ago
What you've said echoes the concept behind the quote "I didn’t have time to write you a short letter, so I wrote you a long one." This, or some variation of it, has been around for quite a while. I think this reveals a fundamental truth about knowledge based work that is inherent to humans. Purposeful simplicity is harder than accidental complexity. > This approach of course takes more time and requires that your management trusts you and is willing to compromise on timelines. I would say that most management and even most programmers don't see the value in this. In my experience focusing on simplicity gives much better long-term results but it has higher and more unpredictable upfront cost. Blasting code onto main is seen as being more productive even though long-term it seems to have much higher overall costs.
gofreddygo 2y ago
simplicity is a noble ambition, but let it not impede progress, for it is subjective and subject to discretion. The art to be learned and practiced is knowing when to cut corners and where to be relentless with yourself and demand that of others. Getting v0.1 out, albeit with murky code and iterating to v2.5 with 10 paying customers is the way to progress. The hard, non-science part is getting management to spend billable hours for no short term benefit. Thats the key skill.

MrMcCall 2y ago

Documentation is useful, when done well. The code is always the authority, and there are very many ways the correct logic can be constructed. How it is constructed is the difference between good enough and excellent. And getting "compromise on timelines" is a most sublime political art. It requires the combination of both a humble, competent manager and an established, successful engineer worthy of trust. Congratulations on your success on those two varied fronts!

nosefurhairdo 2y ago
Thank you! I am indeed very fortunate to have a great manager.
chrsig 2y ago
I think it depends on who the documentation is intended for. I often let public facing documentation be the source of truth for expected behavior unless it's infeasible to coerce the system to that behavior. If the latter does occur, the documentation gets updated. If the question is what does the software actually do, then of course the code, toolchain, and runtime are the authority.
- MrMcCall 2y ago
  Good point. I was only speaking to targeting other developers.
t43562 2y ago
It needs to answer the "why" question most IMO. I can read code and see "how" and perhaps guess "what" but the "why" is missing. It also doesn't have to be that detailed - just a one line comment at the top of a file saying why it's there and what for can make an immense difference to the time it takes to understand code. Class comments are great too if they have in them everything that's NOT in a ChatGPT summary :-). i.e. I can paste code into ChatGPT myself to get a summary if I really wanted to so I don't need that - but I need all the things it doesn't tell you which is basically why the class exists and what it's intended for. The lower down the hierarchy it goes the less comments matter IMO.

mjr00 2y ago

I have the same experience, and I agree that simplicity leads to success. The more things software can do, the harder it is to reason about what it's supposed to do. It's very much the IQ bell curve meme: junior developers only solve the problem at hand, mid-level developers build powerful, but complex frameworks which can solve the problem at hand but also potential future problems, and senior "X10" developers only solve the problem at hand. > There are times during the development of any project where one might be tempted to hack around an issue, or commit the ugly code that seems to work. These are the rough edges that inheritors of a codebase use as evidence that a blank slate would be preferable. Yes, one thing I've learned is to never underestimate the power of inertia in a codebase. When adding functionality, 99% of developers will go for the path of least resistance, which is mimicking whatever patterns already exist. To loop back to the article, this is often due to lack of full understanding; the default assumption is that because something is written in a certain way, that it's the best way. This isn't true; it may not even be the correct way! But copying what already exists has an element of safety built into it, without needing to spend the effort to deeply understand existing code (which tends to be developers' least favorite activity). So if you put in an ugly hack, or have a code structure which doesn't make sense, expect that to persist for years, or decades.

tkiolp4 2y ago
I don’t think it’s up to the developers only to decide. If we are working in a sprint, if all my manager cares about is “shipping impact”, then I’m not going to spend time on things that won’t benefit me in my performance review. I’ll take the shortcuts. Now, if management knew what we know, sure certainly everyone would benefit from that… but that’s not the real world.
anal_reactor 2y ago
> without needing to spend the effort to deeply understand existing code Or, more importantly, explain to others why you're deviating from "standard"
t43562 2y ago
Deviating from the "standard" can make it harder for another maintainer to understand what's going on. IMO setting up reasonable patterns for others to follow is part of a good design. I'm not saying that I personally am great at it - it's an ideal! I think you are right though - very non-understandable things tend to persist because nobody wants to touch them.

worik 2y ago

> I've handed off a few services I built with minimal oversight or documentation. The receiving teams have been able to make changes without my involvement and everyone is happy. I struggle to believe this. Perhaps my personal situation, inheriting a 150k line embedded C programme, which started sprouting weird bugs when ported from X86 -> ARM. > minimal oversight or documentation Why? Why do you not have documentation? > I've been successful in this is because I agonize over simplicity I will break this down: "I've been successful in this " I do not believe this statement > I agonize over simplicity I wonder if the subordinates in your organisation who are not allowed to criticise you, wish you had agonised over documentation (I do not know what power you have over the folks who follow you, I am hypothesising it is a lot) Documentation is very hard. It is harder than writing code because there is no parsing of documentation, no demonstration of correctness. Inaccurate, or lazy, documentation can be worse than useless, but no documentation condemns the system to a slow death I wish my fellow computer programmers would stop making excuses for not doing the extremely hard work of documenting what they were thinking they were doing when they (inevitably) did something slightly differnent

chaps 2y ago
> Why? Why do you not have documentation? > Documentation is very hard. It is harder than writing code because there is no parsing of documentation, no demonstration of correctness. You answered your own question :)
- worik 2y ago
  > You answered your own question :) So "do not do the hard parts"? That is very unprofessional
  - golergka 2y ago
    Achieving desired result is professional. And achieving desired result without doing the hard parts is not only professional, but smart and actually kind of awesome.

jack_h 2y ago

What you've said echoes the concept behind the quote "I didn’t have time to write you a short letter, so I wrote you a long one." This, or some variation of it, has been around for quite a while. I think this reveals a fundamental truth about knowledge based work that is inherent to humans. Purposeful simplicity is harder than accidental complexity. > This approach of course takes more time and requires that your management trusts you and is willing to compromise on timelines. I would say that most management and even most programmers don't see the value in this. In my experience focusing on simplicity gives much better long-term results but it has higher and more unpredictable upfront cost. Blasting code onto main is seen as being more productive even though long-term it seems to have much higher overall costs.

gofreddygo 2y ago

simplicity is a noble ambition, but let it not impede progress, for it is subjective and subject to discretion. The art to be learned and practiced is knowing when to cut corners and where to be relentless with yourself and demand that of others. Getting v0.1 out, albeit with murky code and iterating to v2.5 with 10 paying customers is the way to progress. The hard, non-science part is getting management to spend billable hours for no short term benefit. Thats the key skill.