Talk:Yet Another Design Book?

From APIDesign

Jump to: navigation, search
  • Is there a space before [GoF]?
  • Notice [book.effective] towards end of paragpraph
  • Grammar: Page 1, 3rd paragraph, change to "Despite that, the API clients that compiled their code then are still able to execute their code TODAY, even with the latest versions of those libraries."
  • Punctuation: Page 1, Paragraph 4 - should use dash instead of comma between "the code, that is"
  • Spelling: Page 1, Para 4 - "Overtime" should be "Over time" ("Overtime" is what you get paid when you work too many hours)

--Dmkoelle 20:12, 26 March 2008 (UTC)

  • I'd love to have one extra historical tidbit in the introduction somewhere: what's the origin of the term API? I first remember hearing it in the early 90's, but it's possibly older than that. I spent some time searching using Google, but came up empty-handed. Can you research this?
  • (spelling) I'd prefer seeing a hyphen in the term "object-oriented" throughout the text.
    • Wikipedia is silent on explaining the origin, and I know nothing about it either, so I think I need to skip this
  • (spelling) paragraph 3: "decade old" => "decade-old"

--AdamDingle



  • Third paragraph makes claims about backwards compatibility, which I mostly agree with. However, I got started with platform development just after 4.0 was released and tried to follow examples from the NetBeans Definitive Guide. I remember vividly that I could not get anything to work because of the NoClassDefFound errors on TopManager, so I would recommend making those claims a little less strong in case others remember as well.
    • Fixed in ef6194effbfc, although the first sentence says that only 'some' not all

--TomWheeler

  • Grammar: last paragraph, your tenses are mixed. I would suggest: "Since then, I've known the need for information relating to API design is real. The memory of that presentation has encouraged me whenever I've begun to lose motivation while writing this book. It has helped to remind me that the rules for proper API design that we've discovered need to be documented.

--RichUnger

AndreiBadea Smalltalk and not SmallTalk

I can hardly agree that our APIs are "relatively consistent". This is simply not true when you compare them to APIs for similar purposes. A brief examination of just the things that can be installed in XML layers shows a huge archaeological spread of different styles and techniques, many now deprecated.

  • OK. Explained a bit: 6e521d0cd6ea

--JesseGlick 02:51, 25 March 2008 (UTC)


  • Wording: Pg 6, Para 3: Change "Increasing this asset" to "Increasing the value of this asset"
  • Wording: Pg 6, Para 3: You use the phrase RICH USER BASE, and the paragraph is about money. I think this confuses the meaning of the word RICH - I think you mean to say "extensive user base" as opposed to "wealthy user base". Change the word RICH to something else (like EXTENSIVE).
  • Wording: Pg 6, Para 3: People cringe at the word MONETIZE. Change it to BENEFIT FROM or something similar. Money is not the only bottom line, after all.

--Dmkoelle 20:26, 26 March 2008 (UTC)


  • (spelling) pg. 5, last para: "a bit more engineering design" => "a bit more engineering-driven design"

--AdamDingle 22:45, 27 March 2008 (UTC)

  • I felt the analogy in the first paragraph went on for too long.
  • Punc: Pg 3, Para 1 (i.e., first full paragraph) - should be semicolon (;) before HOWEVER
  • Delete: Pg 3, Para 2: Don't need "Well, obviously." sentence
  • Pg 3, Para 2: "forever" is such a strong word. I was going to recommend saying "almost forever", but I think that weakens the "APIs are with us forever" line, so keep it :)
  • Delete: Pg 3, Para 3: I didn't understand the sentence, "However, one cannot rely on that." THAT seems not well-defined, and I'm not sure why someone would rely on almost invisible functionality. I think you can remove this sentence.
  • Punc: Pg 3, Para 3: End of sentence has an extra period - remove the one after the quotation mark.
  • Punc: Pg 4, Para 0 (i.e., the paragraph that started on Pg 3): need comma after HOWEVER
  • Delete: Pg 4, Para 2: In the sentence that begins with "For example", delete HOWEVER
  • End of section: At this point, it sounds like API design is only about backwards compatibility, and that this is the only differentiating factor between this book and other design books. I suspect there's a lot more that you're going to reveal about API Design that will make the content in this book different from other design books. If you can put some of those in, perhaps at the expense of some of the verbose analogy, that might be beneficial.

--Dmkoelle 20:21, 26 March 2008 (UTC)

This section is really long-winded. The universe analogy makes sense in the latter parts discussing physics, but just seems like excess text in the earlier parts talking about stars.

--JesseGlick 02:36, 25 March 2008 (UTC)

--AdamDingle 22:44, 27 March 2008 (UTC)

  • Page 3, para 3. "If the world behaved like that, it would class with our understanding of the known universe." Our understanding of the world comes from the what we observe, so this does not make sense. Our understanding would simply change to accept what we see.
    • Very good observation. I've changed that to "understanding of the universe as we perceive it today".
  • I agree with Jesse. This text about stars is all deep and interesting, but IMHO does not really fit in a book about API design.

--TomWheeler Thu Mar 27 21:16:22 CDT 2008


Most of the advice you present throughout this entire part is specific to Java. It's true that a good number of your points could be applied to other languages, but there's no way that someone who doesn't know Java at all could read your book. I"m not sure what you're planning to call your book, but I've become convinced that the whole book is sufficiently Java-specific that "Java" should appear somewhere in the title, i.e. "API Design for Java".

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

Subtitle: Confessions of a Java Framework Architect

Retrieved from "http://wiki.apidesign.org/wiki/Talk:Yet_Another_Design_Book%3F"
Personal tools
buy