Re:Why Not Comments
by erik_seaberg on Tuesday September 10, 2024 @09:49PM
(#41507407)
I have seen a linter that requires
to have a doc comment explaining what getName does and also what it returns. Before git, they sometimes needed to see who wrote it and when.
[ Parent
| on HN ]
Well, so, does this method return the login name of the user ? Or is the "name" field in fact a company convention to return firstname and lastname concatenation ? Oh and if it’s that, what will be the concatenation order ? It doesn’t seems like it’s a parameter but is it configurable somewhere ? Is this automatically defined somehow ? Is it hardcoded ? Or is there a name field in the database and if yes, what does it represent ? Etc …
Re:Why Not Comments
by franciscop on Wednesday September 11, 2024 @09:22AM
(#41511108)
Within the code you'd have `return this.user.firstName + ' ' + this.user.lastName;` or similar, which can explain the details of how it works when you look into it.
I'm not super opposed to that, honestly. Doc comments are coloured differently from code, and really help you scan through a file quickly to find the next function. It honestly doesn't take more than a couple seconds to write, and (I find) it really helps readability enough to be worth it.