Apidesign at 05:46, 14 June 2008 - 2008-06-14 05:46:52

←Older revision Revision as of 05:46, 14 June 2008
Line 10: Line 10:
# 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.
# 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.
 +
 +
--[[User:TomWheeler|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 <tt>this</tt> from the constructor, is this what you meant?
 +
 +
--[[User:AndreiBadea|AndreiBadea]] 09:13, 7 April 2008 (UTC)
 +
 +
# 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.
 +
 +
--[[User:TomWheeler|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.
 +
 +
--[[User:AndreiBadea|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.
 +
--[[User:RichUnger|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.
 +
 +
--[[User:RichUnger|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.
 +
 +
--[[User:AdamDingle|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., <tt>value</tt> or <tt>newValue</tt>.
 +
 +
There is an inconsistency between the Javadoc of <tt>Item</tt>'s constructor, and that of the <tt>addChangeListener</tt> 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 <tt>Accessor</tt> to be named <tt>ItemAccessor</tt>. Similar for <tt>AccessorImpl</tt>. Many readers will use the examples as they are in the book, so the examples must show best practices.
 +
 +
--[[User:AndreiBadea|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.
 +
 +
--[[User:JesseGlick|JesseGlick]] 00:30, 8 April 2008 (UTC)
 +
 +
 +
# Page 76: Javadoc of setValue method should say "Anyone can set the value of the item." The words "set the" were missing.
 +
# 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.
 +
 +
--[[User:TomWheeler|TomWheeler]] Sat Apr 12 19:13:37 CDT 2008
 +
 +
 +
On page 76, "class item" should be "class Item".
 +
 +
--[[User:AdamDingle|AdamDingle]] 00:36, 13 April 2008 (UTC)
 +
 +
 +
'''Fixed a bit as 8577a4d13185'''
 +
 +
 +
First paragraph: SmallTalk should be Smalltalk.
 +
 +
The <tt>Executor</tt> and <tt>Configuration</tt> example: either <tt>Configuration</tt> 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 <tt>create</tt> method). The <tt>Mutex.Privileged</tt> does the same, but then again it was probably created before the friend accessor pattern was invented?
 +
 +
--[[User:AndreiBadea|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?
 +
 +
--[[User:JaroslavTulach|JaroslavTulach]] 12:29, 7 April 2008 (UTC)
 +
 +
No, that would only obfuscate the example. But consider making <tt>create</tt> 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.
 +
 +
--[[User:AndreiBadea|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.
 +
 +
--[[User:JesseGlick|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.
 +
 +
--[[User:AdamDingle|AdamDingle]] 00:52, 13 April 2008 (UTC)
 +
 +
 +
# 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).
 +
--[[User:TomWheeler|TomWheeler]] Sat Apr 12 19:13:37 CDT 2008
--[[User:TomWheeler|TomWheeler]] Sat Apr 12 19:13:37 CDT 2008

Apidesign: New page: '''Fixed: f4219513dece''' Regarding "public static final constants": # These are not constants at all if the type is neither primitive nor String. Definitely avoid nonconstant fields, eve... - 2008-06-14 05:43:49

New page: '''Fixed: f4219513dece''' Regarding "public static final constants": # These are not constants at all if the type is neither primitive nor String. Definitely avoid nonconstant fields, eve...

New page

'''Fixed: f4219513dece'''

Regarding "public static final constants":
# These are not constants at all if the type is neither primitive nor String. Definitely avoid nonconstant fields, even if static and final.
## Why you think public static final Object CONST_EMPTY = new Object(); is not constant?
# 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.
# Java 5 enumerations should be encouraged where the value is arbitrary. A constant is appropriate if the value is independently motivated.

--[[User:JesseGlick|JesseGlick]] 00:14, 8 April 2008 (UTC)

# 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.

--[[User:TomWheeler|TomWheeler]] Sat Apr 12 19:13:37 CDT 2008