undefined | Better HN

0 pointsbccdee1y ago0 comments

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.

0 comments

david-gpu1y 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.

bccdeeOP1y 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.

j / k navigate · click thread line to collapse