Effective Java (Remarked) - Methods

Item 38: Check parameters for validity (safe, error-prone)

To summarize, each time you write a method or constructor, you should think about what restrictions exist on its parameters. You should document these restrictions and enforce them with explicit checks at the beginning of the method body. It is important to get into the habit of doing this. The modest work that it entails will be paid back with interest the first time a validity check fails.

When use? always.

Item 39: Make defensive copies when needed (safe, error-prone, stability)

You must program defensively, with the assumption that clients of your class will do their best to destroy its invariants. In summary, if a class has mutable components that it gets from or returns to its clients, the class must defensively copy these components. If the cost of the copy would be prohibitive and the class trusts its clients not to modify the compo- nents inappropriately, then the defensive copy may be replaced by documentation outlining the client’s responsibility not to modify the affected components.

When use? always.

Item 40: Design method signatures carefully (design, safe, error-prone, readability)

Choose method names carefully. Names should always obey the standard naming conventions (Item 56). Your primary goal should be to choose names that are understandable and consistent with other names in the same package.

When use? always.

Item 41: Use overloading judiciously (design, safe, error-prone, readability, stability)

To summarize, just because you can overload methods doesn’t mean you should. You should generally refrain from overloading methods with multiple sig- natures that have the same number of parameters. In some cases, especially where constructors are involved, it may be impossible to follow this advice.

When use? always.

Item 42: Use varargs judiciously (design, safe, error-prone, readability, stability)

In summary, varargs methods are a convenient way to define methods that require a variable number of arguments, but they should not be overused. They can produce confusing results if used inappropriately.

When use? always.

Item 43: Return empty arrays or collections, not nulls (safe, error-prone, stability)

In summary, there is no reason ever to return null from an array or collection-valued method instead of returning an empty array or collection. The null-return idiom is likely a holdover from the C programming language, in which array lengths are returned separately from actual arrays. In C, there is no advantage to allocating an array if zero is returned as the length.

When use? always.

Item 44: Write doc comments for all exposed API elements (design, safe, readability)

To summarize, documentation comments are the best, most effective way to document your API. Their use should be considered mandatory for all exported API elements. Adopt a consistent style that adheres to standard conventions. Remember that arbitrary HTML is permissible within documentation comments and that HTML metacharacters must be escaped.

When use? always.