76
P3trur0
8y

/**
* It gets the user name
*/
public String getUsername() {
return this.username;
}

Comments
  • 8
    It's good to follow proper conventions everywhere. It's a nice practice.

    In case you need a verification later in future this functions are really useful.
  • 8
    So, what is your suggestion to improve this documentation? In my opinion everything is told what needs to be told. Okay, if you are looking for completeness you might add this line:
    * @return The username.
  • 12
    The comment is stating the obvious, which is bad. Ideally, you write the code so that no comment is needed. You may need comments to explain the why, but if you need to comment the what, then you probably need to make the code itself clearer.
    The problem here is with doc systems such as Doxygen, and the convention that all functions must have comments, even the ones that don't need it.
  • 2
    I definitely agree with @Gauthier
  • 1
    @Gauthier exactly. This looks like a comment, used to auto-generate an api documentation. It would be inconsistent to leave it out. As a developer I know of systems like DoxyGen, so I can ignore these comments, which are stating the obvious quickly. I read these type of comments only if I don't understand the method anyway. So this does not bother me.
  • 0
    @Yeah69 Agreed. It mostly bothers me when I feel forced to write one.
  • 3
    @Gauthier But this a javadoc comment. It's not a normal comment for explaining what this is doing. I don't see why it is bad.
  • 0
    I tend to make my functions self explanatory but I my OCD gets triggered whenever a well documented class has methods without summaries so it's usually all or nothing with my docs even if they're just stating the obvious, I'll at least try to make them witty or sarcastic.
  • 0
    If username it's a private field and you want only get it without make someone who use your class can set it to prevent some data inconsistency, it's not properly information hiding but it can be a good practice depending on what are you doing.
  • 0
    Or else it gets the hose again.
Add Comment