I see Codacy making this comment on a PR:
+ * Helper method to ensure the program is set to the given workflow by doing the validations
+ * @param workflow
Codacy Issue found: At-clause should have a non-empty description.
I vote we disable this: we have so many boilerplate methods in our code (unfortunately) that it’s just not worth documenting obvious parameters.
@teleivo, what do you think?
Do you mean if you add a new method and don’t fill out the javadoc parameter?
If we want javadocs that have a parameter description I think we should keep it in otherwise we will not get to there. And update our tools (templates, IDE settings) to do the boring job.
In case we have parameters where its really obvious like what you showed
workflow I hope there is an easy fix to that.
In Eclipse you can manipulate Code Templates like
which does the job for setters well. Unfortunately the
just adds the empty
Maybe someone else (an IDE wizard) has a solution for us
ah, Ive just seen the commit that caused this. Well in this specific commit, these are private methods which are very short and have meaningful names, I dont think javadocs are needed there at all. Mostly because they dont add any value IMHO.
For getters and setters I wish we could just add a @Property annotation and get rid of the methods.
We also could use Kotlin
I didn’t actually look at the specific code in this case, I was thinking about this in general.
For me, javadoc that provides no information is worse than useless.
The worst case is what eclipse generates for getters/setters, e.g.
@param program the program to set and
@return the program. (Because you actually have to read this to realize it’s useless.)
Having an empty
@param is still pointless, but it’s better than the Eclipse way.
My personal preference is just to have no javadoc on methods that don’t deserve it (especially if the dev isn’t going to write anything).
So, I don’t like if our codacy check complains about the “pointless” option but allows the “worst case” option.