3 ms·
But if you have a piece of insane code, especially if it's fairly localised, why is it superior to explain it in a commit message and not a comment right there
by thom 3y ago
But if you have a piece of insane code, especially if it's fairly localised, why is it superior to explain it in a commit message and not a comment right there next to it? Save people the head scratching.
And yes - I do exactly think that the developer should cram the whole issue in the codebase! Those are your acceptance tests, or explicit representations of use-cases or strategies, or service layers, or at the very least some comments lamenting what would otherwise be inscrutable. If your codebase doesn't have a first-class way of describing what it does and why, I don't think it's well-factored.
I totally agree that it's easy to mess up, I just continue to think this terrible workflow of externalising key information about code and why it exists is fundamentally defeatist. I don't think we should settle for it.
- ReptileMan 3y agoThat is a limitation of the tooling we have unfortunately. Every line in the text files that is not code increases the cognitive load of the person when not directly relevant. And unfortunately a lot of development is done on laptops or otherwise screen restrained machines. I agree in principle that the metadata and code should be linked and easily pop in view on demand. But that is not how the tooling currently works and we find only crutches. This is cool paradigm that could make amazing startup. Add in some LLM for buzzword to hook investors. And actually LLM that can trawl all the current sources of knowledge and spitting a one paragraph to glance what and why is going on could even work. But we can't do it while constraining to text files. We need the equivalent of hypertext for code ... and it will be mess in the end.