Talk:Ever Changing Targets

From APIDesign

---

Current revision

• p 40, para 3: "the first version is never perfect": why is this quoted? Who are you quoting? If you mean to emphasize this, italics are a better choice. See e.g. http://en.wikipedia.org/wiki/Quotation_mark#Emphasis_.28incorrect_usage.29 .
• p 40, para 4: "One extreme suggests" => "One extreme is"
• p 40, para 4: "the other prefers" => "the other is"

--AdamDingle 01:55, 28 March 2008 (UTC)

• You've changed the style of capitalization for section headings here.

--Dmkoelle 21:56, 4 April 2008 (UTC)

• p 41, para -2: "the same name and also arguments" => "the same name and arguments"
• p 41, para -2: "but different return type" => "but a different return type"
• p 41, para -2: "the Java languages" => "the Java language"
• p 41, para -2: "and accomodated change of return type to more specific as a valid step of evolution": this sounds awkward. I might suggest "and allowed an overridden method to return a more specific type".
• p 43, para 3: "to advise to create" => "to propose creating"
• p 43, para 3: "that each having different" => "that each have a different"
• p 43, para 3: "write the Java code" => "write Java code"
• p 43, para 4: "source code of Java file" => "source code of a Java file"
• p 43, para 4: "modify the bytecode with higher level" => "modify bytecode using higher-level"
• p 43, para 4: "like jasm" => "such as jasm"
• p 43, para 6: "a valid Java source" => "valid Java source code"
• p 43, para 6: "Simple, effective," => "Simply and effectively,"
• p 44, para 1: "super classes" => "superclasses"
• p 44, para 2: "understaning" => "understanding"
• p 44, para 2: "types of arguments and return value" => "argument types and the return type"
• p 44, para 2: ", just fills it" => ", but fills it"
• p 44, para 2: "Simple, yet powerful." => "This is simple, yet powerful." (incomplete sentence)
• p 44, para -2: "Table Table" => "Table"
• p 44, para -2: "provide by String" => "provided by String"
• p 44, para -2: "object is string" => "object is String"
• p 44, para -2: "accociated" => "associated"
• p 44, para -2: "the code makes call on" => "the code invokes a method on"
• p 45, para 3: "Type control from compiler is missing and there is" => "Type control from the compiler was missing and there are"
• p 45, para 4: "newer version java" => "newer version of Java"
• p 45, para -2: "but guaranteed" => "but are guaranteed"
• p 46, para 1: "there used to be StringBuffer append(Object obj) generic method" => "there had been a generic method StringBuffer append(Object obj)"
• p 46, para 3: "values like integers" => "values such as integers"
• p 47, para 2: "This is both good and bad. Good, because it is easy to understand. Bad, because...": the last two sentences here are incomplete. I'd suggest "This is both good and bad: good, because it is easy to understand, but also bad, because..."
• p 47, para -1: "There is never something like excellent documentation": this is a bit strong. I'd suggest "There is rarely excellent documentation".
• p 47, para -1: "documentation is always out of date" => "documentation is usually out of date" (too strong)
• p 47, para -1: "But, let's suppose that someone did the ideal" => "But let's suppose that someone has done the ideal"
• p 48, figure heading: "How we think our application looks like": delete word "like"
• p 49, figure heading: "How it really looks like": delete word "like"
• p 50, para -3: "My NetBeans experience tells me that people...": Who are the "people" here? API authors? API users? Can you be more specific?

--AdamDingle 02:02, 28 March 2008 (UTC)

• Page 43, para 2: "one actually creates a table.The" -- you need a space after the period
• Page 48: "How we think our application looks like" is odd phrasing; it sounds more natural to use "How we think our application looks"
• Page 49: "How it really looks like" is odd phrasing; it sounds more natural to use "How it really looks"
• Page 50: "Look of the Application in Next Version" is odd phrasing; it sounds more natural to use "How the next version of our application looks"

--TomWheeler Thu Mar 27 21:58:13 CDT 2008

• The captions on the amoeba diagrams are grammatically incorrect. Use "what" instead of "how" in both cases (or remove "like" at the end of each). Actually, I'd change the wording entirely anyway. It makes no sense to say what your API "looks like". If APIs looked like anything you wouldn't need an abstract diagram ;-) Instead, how about, "This perfect circle represents the scope of things you'd like your users to be able to accomplish with your API" and "This amoeba represents the scope of things you can actually accomplish with your API."

--RichUnger Thu Mar 27 21:44:09 PDT 2008

• Page 43: The XML code is off the right edge of the page
• Page 44, para 2: need space between "table.The" (at least, that's what it looks like)
• Page 45: The Java code is off the right edge of the page

--Dmkoelle 21:59, 4 April 2008 (UTC)

The explanation of how virtual methods work could be deleted.

"Primitive constants" should be "compile-time constants" since String's are included. BTW note that (recent versions of) Javadoc display the values of such constants for this reason.

This section is fine but quite specific to Java semantics. For example, quite different techniques are used by C programmers to ensure compatibility of client code compiled against a struct definition, such as leaving null fields in the definition for future expansion.

--JesseGlick 22:43, 7 April 2008 (UTC)

• The captions in Figure 5.1 and 5.2, "How we think our applications look like", is not grammatically correct. Use "How we think our applications look", "How it really looks".
• Figure 5.3: "in Next Version" -> "in the Next Version"

--Dmkoelle 22:01, 4 April 2008 (UTC)

• section title: "Usecase Oriented" => "Use Case Oriented" or "Use Case-Oriented"
• p 51, para -2: "usecase oriented" => "use case oriented" or "use case-oriented"
• p 51, para -2: "Anyway," => "In any case,"
• p 52, para 1: "in order to create really" => "in order to create a really"
• p 52, para 1: "listen to their" => "listen to users'"
• p 52, para 2: "far from the reality" => "far from reality"
• p 52, para 2: "as soon as these real users" => "as soon as real users"
• p 52, para 2: "some API is complete, that is common": replace comma with dash
• p 52, para 2: "of any system, but the fact": replace comma with dash
• p 52, para 3: "a usecases" => "a usecase"
• p 52, para 3: "NetBeans database explorer" => "the NetBeans database explorer"
• p 52, para -2: "register JDBC driver" => "register JDBC driver use case"
• p 53, para 3: "it is believed" => "we believe"
• p 53, para 3: "we use the "usecase", "scenario", "Javadoc" separation" => "we separate use cases, scenarios and Javadoc"
• p 53, para 4: "differences": suggest no quotes here
• p 53, para -2: "the first version is never perfect": suggest no quotes here; italics would be okay
• p 53, para -1: "more consistently on "usecases", "scenarios", and "Javadoc" separation" => "more consistently on the separation of use cases, scenarios and Javadoc"

--AdamDingle 02:15, 28 March 2008 (UTC)

• I'd emend Adam's comments to say, "Use-Case Oriented".
• In general, change noun forms of "usecase" to "use case".
• Page 52: XML is off the right edge of the page

--Dmkoelle 22:02, 4 April 2008 (UTC)

• p 54, para 3: "commitee. That it needs" => "committee, that it needs" (fix spelling, sentence fragment)
• p 54, para 5: "users. Also, that" => "users, and also that" (fix sentence fragment)
• p 54, para -4: "to make sure that the"=> "to make sure that the following"
• p 54, para -4: "Rules for Successful API design": suggest italics instead of quotes
• p 54, para -3: "mapping the general design decisions" => "mapping general design decisions"
• p 54, para -1: "if the usecase driven design" => "If use case-driven design"
• p 55, para 2: "but the tasks are distributed" => "but tasks are distributed"

--AdamDingle 02:19, 28 March 2008 (UTC)

page 26: s/desigh/design --RichUnger Thu Mar 27 21:25:09 PDT 2008

AndreiBadea: Using Linux kernel as an example of compatible development is a bit adventurous, as kernel developers are proud of having no compatibility. JaroslavTulach true, for their modules and APIs between modules, but userspace APIs of kernel are quite stable.

AndreiBadea: "A module of this type has a code base name that ends with '/0'": unclear, reads like "the code base name of official modules ends with '/0'".

AndreiBadea: "A module of this type has a code base name": is it "code base name"? It makes sense, but OTOH the element name in project.xml is code-name-base.

• Made less NetBeans centric: 86f60d7931a7

• section title: "Life-cycle" => "Life Cycle"
• p. 56, para 3: "command line API" => "command-line API"
• p. 56, para 3: "that knows about command line" => "that knows about the command line"
• p. 56, para 3: "that understand files" => "that understands files"
• p. 56, para 3: "to access the command line parameters" => "to access command-line parameters"
• p. 56, para 3: "handling the file open request" => "handling file open requests"
• p. 56, para 3: "appropriatelly" => "appropriately"
• p. 56, para 4: "The APIs created" => "APIs created"
• p. 56, para 4: "long term investment" => "long-term investment"
• p. 56, para 5: "before the API can be said" => "before an API can be said"
• p. 56, para 5: "the chosen way leads" => "the chosen path leads"
• p. 57-8: "In no way do 'cosmetic' to polish" => "In no case should the API authors perform 'cosmetic' changes to polish" (original text is confusing; seems to be in the imperative mood, which is not appropriate here)
• p. 58, para 1: "but improve anything else" => "but may improve anything else"
• p. 58, paragraphs 1-2: There is too much NetBeans-specific detail here; such as the OpenIDE-Modules-Public-Packages information; I'd remove it.
• p. 58, para 1: "a proper mailing list, if no dedicated" => "a proper mailing list. If no dedicated" (run-on sentence)
• p. 58, para 1: "observe api-changes@netbeans.org" => "they may observe api-changes@netbeans.org"
• p. 58, para 1: ", and all changes should be announced" => ". All changes should be announced"
• p. 58, para 3: "with all the related consequence" => "with all the related consequences"
• p. 58, para 3: "/0"): what is this? There's no corresponding opening parenthesis.
• p. 58, para 3: "when source one is droped" => "when source compatibility is dropped"
• p. 58, para 4: "Third party" => "Third-party"

--AdamDingle 03:05, 28 March 2008 (UTC)

• p. 68: "... the linux kernel uses ... dot even ... dot even" (where's the dot odd?)
  • 94509d868934 ;-)

--RichUnger Thu Mar 27 21:27:09 PDT 2008

• I liked this section, I thought it was interesting, and contained stuff I hadn't considered before.
• Page 57, para 5: "Friend API is" - be consistent with the other sections, and remove "API" from that (so, just "Friend is")

--Dmkoelle 22:13, 4 April 2008 (UTC)

• p 67, para 2: "How Many People Have to Die?": ha - I like this expression and may start using it myself!

• p 59, para 5: "optimists" => "optimist's"
• p 59, para 5: "before big bang and after big band" => "before the big bang and after the big bang"
• p 59, para 5: "challenging, but possible, but, it" => "challenging though possible, but it"
• p 60, para 2: "all or nothing switch" => "all-or-nothing switch"; perhaps italics instead of quotes here
• p 60, para 2: "all or nothing" => "all-or-nothing"
• p 60, para 2: "begining" => "beginning"
• p 60, para -2: "phase by phase" => "phase-by-phase"
• p 60, para -1: "bigbang" => "big bang"
• p 66, para -1: "your software project. Even without" => "your software project, even without"
• p 67, para 2: "common to us back are still" => "common to us back then are still"
• p 67, para 5: "Blood, Sweat and Tears" => "blood, sweat and tears"
• p 67, para -1: "stress on the coexistence" => "strees the coexistence"
• p 67, para -1: "multiple different" => "multiple"

--AdamDingle 03:23, 28 March 2008 (UTC)

• Page 60: I noticed several places where periods were outside the quotation marks. They should be inside.
• Page 60, para 3: "De facto this is a win-win situation." This sentence is incomplete and it's best to just delete it.
• Page 60, para 5: "dilemna" should be "dilemma"
• Page 64: "Opps, do not touch this!" should be "Oops, do not touch this!"
• Page 64: "aparent" should be "apparent"
• Page 67: "Block" is a correct and common English word, but when describing the Warsaw Pact countries (plus Yugoslavia), it's "Communist Bloc"

--TomWheeler Thu Mar 27 21:58:13 CDT 2008

• I never understood Tim's faces diagrams. What are the arrows supposed to represent? Who are the faces? I might remove this. One abstract diagram representing an APIs functionality is confusing enough.
• page 78: s/what it we're not/what if we're not

--RichUnger Thu Mar 27 21:29:09 PDT 2008

• Page 66, caption: "Unless... what it were not?" - change "it" to "if"
• Page 67, "How many people have to die": I appreciate and value your history and your experiences, but I wonder if this section might be too touchy.

--Dmkoelle 22:15, 4 April 2008 (UTC)