4 ms·

> A senior engineer writes comments that explain why the code isn't written in another way I suggest providing that sort of high-level decision information in

> A senior engineer writes comments that explain why the code isn't written in another way I suggest providing that sort of high-level decision information in a separate design document. This sort of documentation is written before the code and is presented/discussed with management and peers. That is how it was done at a couple of companies I worked at and it was very effective. Naturally, this was done at the feature level, not on a function to function basis.

solidninja 2y ago
That still needs discipline though - or you end up with N half-finished Confluence pages describing the intention behind the design, all of which are now out of date (and naturally in completely different places). The best way I've seen to keep track of changing things is to have the design linked to the ticket somehow (and if it's a link, then that needs to be a permalink to something that will not go away in a year's time).
anhner 2y ago
I understood that to mean "I've tried doing it x way and it didn't work because y." rather than the functional part. At that point, why not keep the documentation together with the code?
bccdee 2y ago
Then you end up with a design document that corresponds to the code as it existed conceptually before v1 of that code was even written. By the time v1 is written, the design doc will be slightly out of date; by the time the code reaches v3, the document is more than 2 versions out of date. The nice thing about comments is that they're in the code. You can't update the code without at least looking at them; that's more visibilty than you'll get from anything else.
- david-gpu 2y ago
  Design documents were updated as the code changed, obviously. Changing the code without updating the documents would not pass code review if somebody was shortsighted enough to try.
  - bccdee 2y ago
    The kind of design doc that gets presented to management typically isn't checked into the git repo, in my experience. It's a google doc or a wiki page full of planning details, and it gets covered in amendments about whether XYZ will be ready in time and so forth. Having documentation in your repo describing high-level architecture choices and peculiar quirks for future maintainers is nice, sure, but I think that's a separate document with different goals and relatively little overlap. It shouldn't be organized by feature, for starters. Also, if the remarks in that document are granular enough to exist as comments, why not just leave them as comments? Then they're more visible and more likely to remain up-to-date.
zo1 2y ago
I really have to push back against this "design document" stuff. Unless you're writing some sort of uber-complicated, mission-guidance-systems-level code with multiple standards and audit compliance and and and, then you don't this. Alternatively, if your org or reach for this feature is so large that you need to communicate and decide its internals with a lot of people and as such require something like a design document, then you've already failed and you have way too-many cooks in your kitchen. Design by committee is always doomed to failure. Thirdly... if you need a design document to communicate your feature to "management" then that means you don't have autonomy to design this feature as an expert, and again, you have too many "fingers" in your pie. Does this mean you should go into a basement and design your feature like a hermit? No, but a design document shouldn't be your answer, it should be a better team and process around you, as well as a clear business specification.
- david-gpu 2y ago
  We did and it worked great. The process led to not only better designs, but also better visibility for all stakeholders, from technical leads to individual contributors. I'm talking about products that shipped on billions of devices, products that you have most certainly used. It worked.
- bccdee 2y ago
  > Design by committee is always doomed to failure. If you need to communicate your design to a lot of people, that's probably because a lot of people are depending on the output of your work, and they want to make sure it suits their needs. That's not design by committee—that's just designing something that will be widely used.

solidninja 2y ago

That still needs discipline though - or you end up with N half-finished Confluence pages describing the intention behind the design, all of which are now out of date (and naturally in completely different places). The best way I've seen to keep track of changing things is to have the design linked to the ticket somehow (and if it's a link, then that needs to be a permalink to something that will not go away in a year's time).

anhner 2y ago

I understood that to mean "I've tried doing it x way and it didn't work because y." rather than the functional part. At that point, why not keep the documentation together with the code?

bccdee 2y ago

Then you end up with a design document that corresponds to the code as it existed conceptually before v1 of that code was even written. By the time v1 is written, the design doc will be slightly out of date; by the time the code reaches v3, the document is more than 2 versions out of date. The nice thing about comments is that they're in the code. You can't update the code without at least looking at them; that's more visibilty than you'll get from anything else.

david-gpu 2y ago
Design documents were updated as the code changed, obviously. Changing the code without updating the documents would not pass code review if somebody was shortsighted enough to try.
- bccdee 2y ago
  The kind of design doc that gets presented to management typically isn't checked into the git repo, in my experience. It's a google doc or a wiki page full of planning details, and it gets covered in amendments about whether XYZ will be ready in time and so forth. Having documentation in your repo describing high-level architecture choices and peculiar quirks for future maintainers is nice, sure, but I think that's a separate document with different goals and relatively little overlap. It shouldn't be organized by feature, for starters. Also, if the remarks in that document are granular enough to exist as comments, why not just leave them as comments? Then they're more visible and more likely to remain up-to-date.

zo1 2y ago

I really have to push back against this "design document" stuff. Unless you're writing some sort of uber-complicated, mission-guidance-systems-level code with multiple standards and audit compliance and and and, then you don't this. Alternatively, if your org or reach for this feature is so large that you need to communicate and decide its internals with a lot of people and as such require something like a design document, then you've already failed and you have way too-many cooks in your kitchen. Design by committee is always doomed to failure. Thirdly... if you need a design document to communicate your feature to "management" then that means you don't have autonomy to design this feature as an expert, and again, you have too many "fingers" in your pie. Does this mean you should go into a basement and design your feature like a hermit? No, but a design document shouldn't be your answer, it should be a better team and process around you, as well as a clear business specification.

david-gpu 2y ago
We did and it worked great. The process led to not only better designs, but also better visibility for all stakeholders, from technical leads to individual contributors. I'm talking about products that shipped on billions of devices, products that you have most certainly used. It worked.
bccdee 2y ago
> Design by committee is always doomed to failure. If you need to communicate your design to a lot of people, that's probably because a lot of people are depending on the output of your work, and they want to make sure it suits their needs. That's not design by committee—that's just designing something that will be widely used.