3 ms·
Not the OP, but bad/not up-to-date documentation is worse than no documentation at all, as it might take you on the wrong paths while saying that that's the co
by paganel 4y ago
Not the OP, but bad/not up-to-date documentation is worse than no documentation at all, as it might take you on the wrong paths while saying that that's the correct way to do it.
- skybrian 4y agoDocumentation that explains historical context is sometimes useful. The part that gets you is assuming it to be current. It might help to put dates on things?
- MattPalmer1086 4y agoDocumentation at a high level should exist as to what a system does and roughly how it works. Feature changes and so on need to be documented somewhere. The high level design aspects and change. Detailed documentation on software is a waste of time in my opinion. The software itself is indeed the best guide to how it actually works. Having no documentation at all is not good.
- awinter-py 4y agokeep the space shuttle flying, do not simplify this code
- MattPalmer1086 4y agoSafety critical systems is a whole discipline I'd love to know more about.
- awinter-py 4y agothat's a comment from the kubernetes codebase that has been at the center of 'docs vs self-document code vs linters' debates https://github.com/kubernetes/kubernetes/blob/ec2e767e59395376fa191d7c56a74f53936b7653/pkg/controller/volume/persistentvolume/pv_controller.go#L55 https://github.com/kubernetes/kubernetes/blob/ec2e767e593953... and strong agree, safety-critical code is fascinating; I mostly pick my tools for productivity, can't imagine how different my stack would be if it connected to dangerous equipment
- MattPalmer1086 4y agoDidnt know that, thanks! The comment in that code does a pretty good job of explaining why the code looks the way it does.