5 ms·

>code that produced it should be cleaned up and documented before the next project was started. A major why waiting to the end to test document and clean up co

>code that produced it should be cleaned up and documented before the next project was started. A major why waiting to the end to test document and clean up code is a failure. Write beautiful, tested code from the start. Even throwaway code, because half time prototypes, etc end up production.

lifeisstillgood 11y ago
See the middle part "there is not enough time to do it right first time"
- mbrock 11y ago
  And even if there happens to be, check back in six months and see what's happened. Did your beautiful design smoothly accommodate the fix for the tricky issue #5388? Was there enough time then to update your clear documentation, or does the documentation now clearly explain something false? Did the new coworker who implemented that new feature understand the point of your design such that she was able to extend it properly while you were busy for three weeks chasing a deadlock? And so on. Beauty always fades!
  - lifeisstillgood 11y ago
    Agreed
  - davidjnelson 11y ago
    Yup. Unit tests, clean code built via tdd, auto generated docs from interfaces, high level architecture diagrams and explanations on a wiki, instructions on getting your machine / environment set up on a wiki, and api contracts on a wiki are the best documentation from my experience.
seivan 11y ago
You're assuming programmers get the time they need to set up the test environment. Try out a few different libraries to make things easier for testing. Manage quirks and bugs within the tests themselves or test runners and etc. From my PoV that's rarely something we get to allocate time for. The sales people sell "continuous integration" and "tests". But it doesn't mean that we're allowed to allocate time for that.
gozur88 11y ago
At most places I've worked there's not much point in documenting everything meticulously at the start. The users don't know what they want yet, and they won't think through the details until they get the first prototype. What makes sense in testing and documentation is really project dependent. What's right for flight control software is very different from what's right for Yet Another Twitter Clone.
- njharman 11y ago
  I mean programmer documentation, how to build this thing, why was this choice made, what ideas were attempted and abandoned and why, what gotchas, what shortcuts were taken/tech debt incured. A lot of this should be in commit messages and/or "tickets" refed in commit messages. Rest goes into README, code comments. User docs are completely outside my realm as a software developer. My point (and strongly held belief) is NO, when you do testing and documentation is not really project dependent. All projects need to do it from the start. Some, flight control software, need more rigorous process. Everything needs to be viewed through ROI. My contention is too many devs underestimate the return of "doing it right" from the start. and overestimate the effort and effectiveness of doing it later/at the end.

lifeisstillgood 11y ago

See the middle part "there is not enough time to do it right first time"

mbrock 11y ago
And even if there happens to be, check back in six months and see what's happened. Did your beautiful design smoothly accommodate the fix for the tricky issue #5388? Was there enough time then to update your clear documentation, or does the documentation now clearly explain something false? Did the new coworker who implemented that new feature understand the point of your design such that she was able to extend it properly while you were busy for three weeks chasing a deadlock? And so on. Beauty always fades!
- lifeisstillgood 11y ago
  Agreed
- davidjnelson 11y ago
  Yup. Unit tests, clean code built via tdd, auto generated docs from interfaces, high level architecture diagrams and explanations on a wiki, instructions on getting your machine / environment set up on a wiki, and api contracts on a wiki are the best documentation from my experience.

seivan 11y ago

You're assuming programmers get the time they need to set up the test environment. Try out a few different libraries to make things easier for testing. Manage quirks and bugs within the tests themselves or test runners and etc. From my PoV that's rarely something we get to allocate time for. The sales people sell "continuous integration" and "tests". But it doesn't mean that we're allowed to allocate time for that.

gozur88 11y ago

At most places I've worked there's not much point in documenting everything meticulously at the start. The users don't know what they want yet, and they won't think through the details until they get the first prototype. What makes sense in testing and documentation is really project dependent. What's right for flight control software is very different from what's right for Yet Another Twitter Clone.

njharman 11y ago
I mean programmer documentation, how to build this thing, why was this choice made, what ideas were attempted and abandoned and why, what gotchas, what shortcuts were taken/tech debt incured. A lot of this should be in commit messages and/or "tickets" refed in commit messages. Rest goes into README, code comments. User docs are completely outside my realm as a software developer. My point (and strongly held belief) is NO, when you do testing and documentation is not really project dependent. All projects need to do it from the start. Some, flight control software, need more rigorous process. Everything needs to be viewed through ROI. My contention is too many devs underestimate the return of "doing it right" from the start. and overestimate the effort and effectiveness of doing it later/at the end.