What I discovered later was that design documentation, encoding the intent and decisions made during developing a system, helps teams be successful in the short term, and people be successful in the long term.
Our team has a rule that no work should be done on a major feature without a design document that has been vetted by the entire team, and possibly with input from other teams. It is a godsend because it catches so many errors and problems ahead of time. Does it catch everything? No, but it certainly prevents some wrong turns before they happen. And it has proven to be helpful when people challenge us as to why we did it one way instead of another because we document failed ideas with reasons as to why they don’t work.
I recommend teams consider what a little design up front can do for them, especially thinking through many scenarios. It really helps.
Similarly, my team has a rule that any assumptions must be clearly stated. Now granted I am not a professional programmer and I work on team with zero professional programmers, but for the code we do write, this is a must. I wrote a function earlier today that polls an API and does some work with the response and by my team’s rules I had to specify an example of what I assumed the API response looks like under normal circumstances. The code then went on to do some manipulation of that data assuming a normal API response. If someone is trying to debug the code in the future they’ll be able to see what assumptions I made (the API response looks like this) and determine really quickly if the code is failing because the API response looks different now.
It really helps us because the API endpoints can change faster than we write new code. Explicitly documenting the state of the environment when the code was written helps the next person understand what might have gone wrong since the last time the code was changed. It’s usually the API that changed rather than our code mysteriously breaking.
Do you also use that example in a test and assert the outcome of the function is what you desire it to be? Because if you don’t, I predict you would find that hugely helpful.
Stupidly our company requires that any tests have to cover at least 95% of the code. That rule doesn’t apply to code with no tests. So we only use tests in projects where we have the overhead to complete the testing. We’re a team of consultants, not programmers, so we rarely have enough time to write tests with 95% coverage.
What would be a design document for you/your team? How did you ensure that vetting was more than just a rubber stamp?
In several companies I’ve been to, term ‘design document’ meant similar, yet different things. In one, it was a one pager motivating the work, in another it was a free form document where it would be good that one outlines other approaches. But in every situation, there was not a lot of challenging of the content, as if these documents are there just to convince ourselves that we did the due diligence.
This is something the team mandates on itself, it’s not something forced on us. We take it seriously. Design documents often take weeks to be worked out and we present and discuss them in team meetings. In fact, the near final version must be presented to the team before it can be approved.
I guess the answer to your question is that things don’t get rubber stamped because everyone agrees that is a bad idea.
Code doesn’t even say what it does with 100% fidelity. It says what its programmer intends it to do, but if there’s a difference between the development and running system (the developer used Linux, and called killall make to stop processes with the name make. I’m running OpenIndiana, and…bad times) or between what the instruction claims to do and what it actually does (FDIV ought to do a floating point divide), then even that is going to be inaccurate. Not that that comes up frequently in practice, and is usually considered a bug when it does, but it’s more fuel to the fire that “my code is self-documenting” should be given an honourable send-off in.
Our team has a rule that no work should be done on a major feature without a design document that has been vetted by the entire team, and possibly with input from other teams. It is a godsend because it catches so many errors and problems ahead of time. Does it catch everything? No, but it certainly prevents some wrong turns before they happen. And it has proven to be helpful when people challenge us as to why we did it one way instead of another because we document failed ideas with reasons as to why they don’t work.
I recommend teams consider what a little design up front can do for them, especially thinking through many scenarios. It really helps.
Similarly, my team has a rule that any assumptions must be clearly stated. Now granted I am not a professional programmer and I work on team with zero professional programmers, but for the code we do write, this is a must. I wrote a function earlier today that polls an API and does some work with the response and by my team’s rules I had to specify an example of what I assumed the API response looks like under normal circumstances. The code then went on to do some manipulation of that data assuming a normal API response. If someone is trying to debug the code in the future they’ll be able to see what assumptions I made (the API response looks like this) and determine really quickly if the code is failing because the API response looks different now.
It really helps us because the API endpoints can change faster than we write new code. Explicitly documenting the state of the environment when the code was written helps the next person understand what might have gone wrong since the last time the code was changed. It’s usually the API that changed rather than our code mysteriously breaking.
Do you also use that example in a test and assert the outcome of the function is what you desire it to be? Because if you don’t, I predict you would find that hugely helpful.
Stupidly our company requires that any tests have to cover at least 95% of the code. That rule doesn’t apply to code with no tests. So we only use tests in projects where we have the overhead to complete the testing. We’re a team of consultants, not programmers, so we rarely have enough time to write tests with 95% coverage.
What would be a design document for you/your team? How did you ensure that vetting was more than just a rubber stamp?
In several companies I’ve been to, term ‘design document’ meant similar, yet different things. In one, it was a one pager motivating the work, in another it was a free form document where it would be good that one outlines other approaches. But in every situation, there was not a lot of challenging of the content, as if these documents are there just to convince ourselves that we did the due diligence.
This is something the team mandates on itself, it’s not something forced on us. We take it seriously. Design documents often take weeks to be worked out and we present and discuss them in team meetings. In fact, the near final version must be presented to the team before it can be approved.
I guess the answer to your question is that things don’t get rubber stamped because everyone agrees that is a bad idea.
Code doesn’t even say what it does with 100% fidelity. It says what its programmer intends it to do, but if there’s a difference between the development and running system (the developer used Linux, and called
killall maketo stop processes with the namemake. I’m running OpenIndiana, and…bad times) or between what the instruction claims to do and what it actually does (FDIV ought to do a floating point divide), then even that is going to be inaccurate. Not that that comes up frequently in practice, and is usually considered a bug when it does, but it’s more fuel to the fire that “my code is self-documenting” should be given an honourable send-off in.Here is a HN post with an excellent example of a difference between development and running systems.