5 ms·
> neither code nor comments should be tutorials Why not? To take the example from the article: def userCoworkers(u: User): List[Employee] = u.department
by Archelaos 1y ago
> neither code nor comments should be tutorials
Why not? To take the example from the article:
def userCoworkers(u: User): List[Employee] =
u.departments.flatMap(_.employees)
Why not add a comment like:
// Automatically iterates through all the user's
// departments and assembles a single list of all
// their employees.
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.
- arresin 1y agoSame. 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.
- AdieuToLogic 1y agoIMHO, 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.
- Xss3 1y agoId argue the function name and placement are bad. I have coworkers that arent in my department. If its not obvious what the method is doing from the name and requires a comment then its a bad name.
- Archelaos 1y agoI would say that this is only true for very, very simple use cases. Even moderately complex code should at least be accompanied with a concise documentation. Here is an example from my work: Consider the case were two database fields should either both be NULL or both must have a value. Instead of 'amount' and 'currency' and documenting the relation, should we really name the fields 'amount_if_currency_is_not_null' and 'currency_if_amount_is_not_null'? And is it really sufficient to define 'amount' as INTEGER without any documentation and then demand that everyone new to the project and not familiar with financial calculation immediately understands that the value is given in the lowest unit of the associated currency, i.e. cents for US dollar vs. one hundred millionth of a bitcoin vs. Icelandic króna (which has no subdivision). Good luck to find a short name that makes that obvious.
- Xss3 1y agoYou dont mix business logic and data like that. You name the fields currency and amount and have the business logic rejecting invalid pairs. You should use a currency type for the other issue, not an integer.
- Xss3 1y agoUpon reflection a proper strong currency amount type that has a strongly typed currency property as a requirement for existence makes sense.