▲ | Archelaos 8 hours ago | |
> neither code nor comments should be tutorials Why not? To take the example from the article:
Why not add a comment like:
Perhaps a note should also be added explaining why the domain model opted for u.departments and not for something more natural like u.company.departments. And the comment should also explain, why we do not filter for duplicates here.I insert many such comments into my own code when I use a rare language feature or a somewhat peculiar element of the domain model. This makes refactoring my own code much easier, faster and more bug-resistant. When composing code, it is generally simple and quick to add such a comment, as it is merely a matter of writing down the result of my immediate thought process. | ||
▲ | AdieuToLogic 2 hours ago | parent | next [-] | |
IMHO, comments are required for capturing "the why." Code captures how it works, when it is used, and what it does. But only the author(s) can capture why it exists via commenting. | ||
▲ | bn-l 7 hours ago | parent | prev [-] | |
Same. And it’s helpful not just for other people but for me also when I’ve forgotten how it works and now there’s no one to ask. |