3 ms·

While it is useful to have a short comment like this in the code as a quick reminder, such design choices belong in a more detailed technical design document wh

While it is useful to have a short comment like this in the code as a quick reminder, such design choices belong in a more detailed technical design document which explores multiple design options and provides rationale for making the final choice. Usually, there will be a trove of useful stuff in code review comments etc that should find its way into such a technical design document. To ensure it gets done alongside code, I prefer wiki docs that sit alongside code and doc changes can be part of the same code commit as well.

xmprt 4y ago
If comments can lie then design documents can lie even more. There are three tiers of documentation in my mind. Code, comments, and documents. Code can't lie (although it can be misleading with improper naming or bad abstractions). Comments can be completely false (although they're easier to catch because the comments sit alongside the code) Design docs almost always lies and it's hard to catch the lies because a design doc written 2 months ago is never going to match the resulting code perfectly. In my experience, people rarely update documentation unless there's a dedicated employee/developer advocate who is helping enforce and drive the culture.
- trashtester 4y ago
  > a design doc written 2 months ago is never going to match the resulting code perfectly. That depends how you're writing design docs. If a design doc contains arbitrary flowchars about what happens in the code, it will change. But if you come up with designs similar to design patterns, you can document the pattern once, and use it in your code the way you use a design pattern. Concepts that span a large codebase is also enormously paintful to figure out from reading the code. For instance object models / microservice architectures, complex state machines or security frameworks are hard to catch implicitly from reading the code.
- vincnetas 4y ago
  You got it backwards. You have design documents and they should be source of truth. If you change your code and code now contradicts design docs, it's the code that is wrong. Said that design docs should not be super detailed, they should capture general assumptions and conventions, code can have all the details, but code cant contradict design docs. But when you too lazy to update design docs, code and docs get out of sync. And it's always easier to just leave docs unchanged, because "hey, code works". It's a bit similar to word processor compatibility issues on linux and windows. You can have perfect implementation of specification on linux, but Microsoft does some changes that are not specification compliant and now a doc created on windows does not open on linux. And from users perspective it's linux fault that file can't be opened, even though it's actually microsoft that is not following specs.
  - quickthrower2 4y ago
    Your last paragraph is pretty much why in practice the design specs go out of sync. The reward systems reward correct code not correct docs. Unless the team is very strict and code reviews doc changes.
drekipus 4y ago
> such design choices belong in a more detailed technical design document which explores multiple design options and provides rationale for making the final choice. We're talking about a line of code that has 2 words here. "A method to sort something" and "something to sort".
DoingIsLearning 4y ago
> such design choices belong in a more detailed technical design document I agree with you but in my experience unless you are writing this documentation in a regulated industry (with external incentives to keep the documentation up to date) the technical docs will eventually go stale or out-of-sync with the actual implementation.
AlotOfReading 4y ago
In my experience, source code tends to survive forever. Things outside it don't, whether through attrition via document retention periods, the IT department noticing nobody uses that document archive and shutting it down to cut costs (not before being told "nobody uses that!"), or hundreds of other possible causes. I've worked on code older than I am and those little comments that probably should have been design docs were a godsend. Nothing else had survived.

xmprt 4y ago

If comments can lie then design documents can lie even more. There are three tiers of documentation in my mind. Code, comments, and documents. Code can't lie (although it can be misleading with improper naming or bad abstractions). Comments can be completely false (although they're easier to catch because the comments sit alongside the code) Design docs almost always lies and it's hard to catch the lies because a design doc written 2 months ago is never going to match the resulting code perfectly. In my experience, people rarely update documentation unless there's a dedicated employee/developer advocate who is helping enforce and drive the culture.

trashtester 4y ago
> a design doc written 2 months ago is never going to match the resulting code perfectly. That depends how you're writing design docs. If a design doc contains arbitrary flowchars about what happens in the code, it will change. But if you come up with designs similar to design patterns, you can document the pattern once, and use it in your code the way you use a design pattern. Concepts that span a large codebase is also enormously paintful to figure out from reading the code. For instance object models / microservice architectures, complex state machines or security frameworks are hard to catch implicitly from reading the code.
vincnetas 4y ago
You got it backwards. You have design documents and they should be source of truth. If you change your code and code now contradicts design docs, it's the code that is wrong. Said that design docs should not be super detailed, they should capture general assumptions and conventions, code can have all the details, but code cant contradict design docs. But when you too lazy to update design docs, code and docs get out of sync. And it's always easier to just leave docs unchanged, because "hey, code works". It's a bit similar to word processor compatibility issues on linux and windows. You can have perfect implementation of specification on linux, but Microsoft does some changes that are not specification compliant and now a doc created on windows does not open on linux. And from users perspective it's linux fault that file can't be opened, even though it's actually microsoft that is not following specs.
- quickthrower2 4y ago
  Your last paragraph is pretty much why in practice the design specs go out of sync. The reward systems reward correct code not correct docs. Unless the team is very strict and code reviews doc changes.

drekipus 4y ago

> such design choices belong in a more detailed technical design document which explores multiple design options and provides rationale for making the final choice. We're talking about a line of code that has 2 words here. "A method to sort something" and "something to sort".

DoingIsLearning 4y ago

> such design choices belong in a more detailed technical design document I agree with you but in my experience unless you are writing this documentation in a regulated industry (with external incentives to keep the documentation up to date) the technical docs will eventually go stale or out-of-sync with the actual implementation.

AlotOfReading 4y ago

In my experience, source code tends to survive forever. Things outside it don't, whether through attrition via document retention periods, the IT department noticing nobody uses that document archive and shutting it down to cut costs (not before being told "nobody uses that!"), or hundreds of other possible causes. I've worked on code older than I am and those little comments that probably should have been design docs were a godsend. Nothing else had survived.