Ranter
Join devRant
Do all the things like
++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatar
Sign Up
Pipeless API
From the creators of devRant, Pipeless lets you power real-time personalized recommendations and activity feeds using a simple API
Learn More
Comments
-
tahnik389888yIt'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. -
Yeah6916298ySo, 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. -
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. -
Yeah6916298y@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.
-
tahnik389888y@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.
-
TheBoJaN138yI 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.
-
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.
Related Rants
/**
* It gets the user name
*/
public String getUsername() {
return this.username;
}
undefined
wk16