Sign in to your account. Identified at comment ,. All methods should have a javadoc in main code, including private methods. Somehow our config is broken that it is not reporting this.
The text was updated successfully, but these errors were encountered:. Sorry, something went wrong. We just need to set the scope in MissingJavadocMethodCheck to private, the same as JavadocMethodCheck, in our configuration and it will resolve the issue. We should review the scopes of the other Missing checks to ensure they match their other. You might think that it's best to use an array on Monday, change your mind and use a Queue on Tuesday, and change your mind yet again and use a TreeMap on Wednesday.
You want to retain as much flexibility as possible without over-committing. The client of a private method is somebody who wants to add a new public method to your class, and will potentially use your private method to do so. As a result, it's ok to talk about some internal details such as your fields, but still not ok to talk about how your method works. Note that the expectations for private method header comments are nearly identical to those for public method header comments, except that our target audience has shifted.
For public method header comments, the clients are people who are interested in using your class in some way. For private method header comments, the clients are people who are interested in adding a new public or private method to your class, and will be using though not modifying your private method in some way.
As a consequence, you should still take care to comment on all preconditions and postconditions, and describe all parameters, potential exceptions, expected behavior, and so forth. However, because the client is somebody who is extending the functionality of your class, the client will naturally be able to view the specific fields and therefore can deduce quite a bit about what algorithms and data-structures your class uses.
Because of that, there's really no point in trying to word your private method header comments in such a way to try and hide information about fields, data-structures, and algorithms from your client. Rather, it's encouraged to talk about those sorts of things since it's potentially useful for your client to understand how exactly your method manipulates and works with your fields. However, do keep in mind that your comments should NOT talk about how specifically your method works.
That still counts as implementation detail, since there's no need for the client to know how exactly your private method works. While having redundancy in code is very bad and should be avoided whenever possible, redundancy in comments is sometimes unavoidable and is not as big of a deal.
If your method header comments for two methods are very similar, it's acceptable to have some duplicated information. If those two comments are for public methods, it's acceptable to have one comment refer to the other. If you have a public method and a private method which are very similar for example, for public-private recursion problems , you should adjust your comments for the private method to focus more on the differences between the two methods.
More examples follow below. When you have two public methods which are very similar, you are allowed to let them explicitly mention each other.
For example, this would be an example of acceptable commenting:. Even though pickFlower and pickFlowers have very similar preconditions and postconditions, the simpler method pickFlower can simply state that it's equivalent to calling another method in a certain way and thus avoid having to repeat a lot of the comments.
However, if you have a public method and a private method which are very similar for example, when writing a pair of public-private methods for recursion problems , you cannot have the public method refer to the private one. After all, the client of the class is unable to view any of your private method header comments so would not be able to view what you are referring to.
If you have a publicly accessible version of your docs such as if you're generating them and publishing them online for end-users , it makes sense to document anything your end users will need to know. This includes all public classes and methods. My opinion is that you shouldn't use javadocs on internal and private methods and classes.
The main reason is that javadocs primarily benefit people who consume, not maintain, your code. On the other hand, you do need to keep notes and comments on your own code, which is often internal. In this case, I would suggest normal comments eg. On the other hand, if a method becomes public, it can be useful to convert those comments into a true javadocs.
Javadocs have the benefit of forcing you to think about and document every parameter, exception, and return value.
You don't have to javadoc anything, but it's very helpful to. More javadocs are never a bad thing. Per your question, if you use the javadoc documentation compiler, javadocs will be compiled for protected methods, but not private methods.
There's no reason they can't still be used as code comments, though. If you add any files,it will delete all existing files related to this question- questions only answer remains unchanged. Spillner defends that the proper way to deal with this should be to move these methods to other classes and make them public. This method may absolutely change, even in patch releases, and should not be relied upon to even exist.
All being said, I do think there are cases in which private methods are used in a wrong way. Like any other tool, they can be abused. You should probably watch out for some red flags. When a private method is so complex that you really, really wished you could unit test it…then it probably should be made public. What about a private method that contains duplicated code, as in, copied and pasted from another class…?
Get rid of the duplication immediately! At some point, you have to make some choices. How complex is complex enough for a private method to need unit testing?
How to properly tell about different levels of abstractions? The best tip I can offer is: Use an extra pair of eyes. Always have another person look and examine your code before you check it in. Not only technical knowledge, but domain knowledge as well, and that can make the difference when the time comes to make those tough decisions.
It seems to me that some of the people that claim to be arguing against private methods are in fact arguing against issues that are orthogonal to private methods ; you can violate SRP with and without private methods; you can mess with internal mutable state with and without private methods, and so on. Software development is an art, full of trade-offs and uncertainty.
0コメント