Comment by open_
3 months ago
This is quite a valuable comment that I agree with 100% and from what I understand, a highly unpopular opinion. I hope more people see this.
3 months ago
This is quite a valuable comment that I agree with 100% and from what I understand, a highly unpopular opinion. I hope more people see this.
There is consensus documenting why you did something is good (which is what root comment is talking about). Documenting what you did is commonly thought to be a crutch for writing unreadable code.
I hate the second thought, because not documenting is clearly not stopping people from committing the unreadable code. Instead we get "my code is self-documenting, I'm not going to write documentation".
And as for the third opinion of "the documentation becomes out of date when the code changes", I would prefer slightly incorrect comments to decipher code rather than no comments to decipher code. Doubly so because I can compare the comments to historical revisions.
While I _absolutely_ agree with those sentiments, I have seen nothing like consensus on them myself (in mostly tech startups, but also fintech, and financial (yes, those are different things)). If I limit it to programmers I respect, the percentages go up, but to _maybe_ 75% tops.
The idea that code should communicate intent, whether by comments or other means, is popular and common. It ends up being somewhat difficult to execute. In practice, you have to write code like you write prose. Keep your audience in mind, and be aware of the contextual information available to that audience, and write code that will make sense to your particular audience, ignoring the needs of non-audiences. The tricky part is when your audience includes people in the future. But even how you account for a future of missing design docs and broken links will vary based on things like team composition, business/problem domain, is this open-source or not, etc.