Talk:Do Not Expose More Than You Want

From APIDesign

Fixed: f4219513dece

Regarding "public static final constants":

1. These are not constants at all if the type is neither primitive nor String. Definitely avoid nonconstant fields, even if static and final.
   1. Why you think public static final Object CONST_EMPTY = new Object(); is not constant?
2. True constants can also be problematic because, as mentioned in a previous chapter, the value is inlined into the caller and so cannot ever be changed.
3. Java 5 enumerations should be encouraged where the value is arbitrary. A constant is appropriate if the value is independently motivated.

--JesseGlick 00:14, 8 April 2008 (UTC)

1. Page 71: The anecdote about the performance of compiled versus interpreted code is duplicted from a previous chapter. It should exist in one place or the other, but not both.

--TomWheeler Sat Apr 12 19:13:37 CDT 2008

Fixed: 68efa8b9841a

The sentence "you can synchronize better when invoking a factory method" needs more detail. Other reasons for factory methods are well described in Effective Java, but not this one. One reason to use a factory method is to avoid escaping this from the constructor, is this what you meant?

--AndreiBadea 09:13, 7 April 2008 (UTC)

1. Page 72: What is the purpose of declaring that Template extends Object? It's implicit and does not need to be declared unless you're trying to make some point that I must have missed.

--TomWheeler Sat Apr 12 19:13:37 CDT 2008

Fixed: f8cac2a753b7

The examples in this section are of little value -- most, if not all, readers know how to override a method. Instead, more useful would be an example of what might go wrong when a class not designed for subclassing is left subclassable. The sentence "it is better to disallow this behavior" should perhaps be expanded. Why is it better? Even if you give more details in subsequent chapters, you should still give some objective reasons here.

--AndreiBadea 09:22, 7 April 2008 (UTC)

This section could use another example that shows the danger of a non-final class (e.g. the 2nd version changes its return type to be more general, breaking overridden methods) Say, for example, a method returns a Set and is modified later to return a Collection. Client code does not break, but anyone overriding now has a compile error. --RichUnger 22:40, 10 April 2008 (UTC)

Fixed: 884544ab39ec

This section communicates its point well, but given the popularity of Spring, a mention of IoC is probably warranted. Just referencing the later section on IoC is fine.

--RichUnger 22:40, 10 April 2008 (UTC)

In the first paragraph in this section, it's not clear to me just what you mean by "convenience base classes". Please clarify. Your following example using javax.swing.Action might help, but when reading it it's not obvious to me what the relationship between Action and AbstractAction is. Is AbstractAction a class? An interface? Which inherits from which? I could go look at the Javadoc, but your book should be written so that I don't have to.

--AdamDingle 00:35, 13 April 2008 (UTC)

Fixed: fd5ed0a24e62

Slightly bad coding style in the accessor example:

public final class Item {
    ...
    public void setValue(int x) {

It is customary to name setter pararameters after the name of the property, e.g., value or newValue.

There is an inconsistency between the Javadoc of Item's constructor, and that of the addChangeListener method ("constructor for friends" vs. "only the impl package can listen"). Why not "only friends can create instances" and "only friends can listen"?

The common NetBeans usage calls for Accessor to be named ItemAccessor. Similar for AccessorImpl. Many readers will use the examples as they are in the book, so the examples must show best practices.

--AndreiBadea 09:29, 7 April 2008 (UTC)

It is worth noting that JSR 294 would provide a supported way in the language to mark members as accessible to other packages within the same module only.

Figure 6-1 is baffling.

--JesseGlick 00:30, 8 April 2008 (UTC)

1. Page 76: Javadoc of setValue method should say "Anyone can set the value of the item." The words "set the" were missing.
2. I agree with Jesse about Figure 6-1. I don't understand the picture nor the metaphor about space travel. I don't think most readers would understand the concept of teleinterfaces after reading what is on page 79, so perhaps more explanation is warranted.

--TomWheeler Sat Apr 12 19:13:37 CDT 2008

On page 76, "class item" should be "class Item".

--AdamDingle 00:36, 13 April 2008 (UTC)

Fixed a bit as 8577a4d13185

First paragraph: SmallTalk should be Smalltalk.

The Executor and Configuration example: either Configuration is a public API class (wrong since it confuses non-privileged users), or is a non-public class (wrong since it is referenced by the public create method). The Mutex.Privileged does the same, but then again it was probably created before the friend accessor pattern was invented?

--AndreiBadea 09:38, 7 April 2008 (UTC)

Andrei, do you mean that I should also use accessor pattern in this example? I can mention that this would be preferable, but I do not think it is wise to mix two patterns in one. Don't you think that as well?

--JaroslavTulach 12:29, 7 April 2008 (UTC)

No, that would only obfuscate the example. But consider making create package private so as to emphasize that the method is only for privileged users. I think that the reader who has gone through the accessor patter section will make the connection.

--AndreiBadea 19:39, 7 April 2008 (UTC)

"completely safe and secure" - well, someone using reflection can still get privileged access. But this is also preventable with a SecurityManager.

Note that our Mutex is actually a read-write lock. Using our mistaken name in the book's example is liable to be confusing.

--JesseGlick 00:38, 8 April 2008 (UTC)

When I read your example with javax.swing.text.Document and AbstractDocument, it wasn't clear to me whether Document was an interface or a class, and it wasn't clear which inherited from the other. I had to go look that up in the Javadoc; your text should be written so that I don't have to.

--AdamDingle 00:52, 13 April 2008 (UTC)

1. Page 85: I really liked the examples about design flaws in Swing. I like that you're teaching people how to design APIs by pointing out both the right way and the wrong way of doing it, particularly when those examples use something readers are likely to already know (like Swing).

--TomWheeler Sat Apr 12 19:13:37 CDT 2008