Home Commenting public vs private methods

Public vs. private comments

Previously, we stated that there are three kinds of methods: class header comments, method header comments, and inline comments.

We are going to extend this model further by taking a look at the differences between public method header comments, and private method header comments. We expect slightly different things from the different types of method headers.

Public comments

The client of a public method is somebody who might want to use your code. As a result, you should avoid including info about how exactly your class and methods work and instead focus on commenting external behavior.

Private comments

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.

Redundancy in comments

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.

Comment your exceptions

Whenever you have a method that could potentially throw an exception (IllegalArgumentException, FileNotFoundException, etc), you should mention that your code could throw this exception, and under what conditions.