3 ms·
Just like comments, documentation is a code smell. Too much documentation is an indication that your codebase is in need of a major overhaul.
by patrick451 5y ago
Just like comments, documentation is a code smell. Too much documentation is an indication that your codebase is in need of a major overhaul.
- shoo 5y agodocumentation can be invaluable when it explains the underlying requirements or constraints behind a particular implementation. if you can just see the implementation but have no documentation of what the actual requirements and constraints are, what problem is trying to be solved, there's no way to evaluate if the code is correct or not, even if the code is structured in a way that looks subjectively clean, elegant, performant, etc. if the codebase is super elegant but is solving a problem that is no longer relevant to the organisation, the correct move is likely to delete or archive the repo and avoid the ongoing cost of maintaining it. if you are new to a codebase and look at a particular implementation of something without any context, maybe it looks very strange and should "obviously" be refactored to align more with some standard application design principle or heuristic. but without the extra context of "oh originally it was written the standard way but for operational / business reasons X Y Z we had to contort it this way to avoid causing production outages due to interactions with bugs in the A B C layer" or "oh that was written by a contractor in a hurry who we got rid of for underperforming, yeah there's no reason it had to be that way, cleaning it up is on the backlog when we next have a reason to touch that part of the code" you're operating blind.