Hacker News Reader

Comment by anotherevan | Hacker News Reader

    Cursor cursor = getCursor(); // Cursor.

View on HN

I have seen a linter that requires

  class User {
    public String getName() { ... }
  }

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.

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 …

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.

Reply on news.ycombinator.com