Talk:The Motivation to Create an API

From APIDesign

More on topic than the previous chapter. Still quite a lot of preachy text without much in the way of specific information or advice. Could likely be trimmed down quite a bit.

--JesseGlick 22:38, 26 March 2008 (UTC)

Good, reads fairly well.

• "it is almost essential for the success of clueless reuse to let the APIs closely reflect the internals of such libraries" - while this is definitely true in some cases, in other cases I don't think it holds. If you can manage to truly hide a very complex internal implementation behind a simple and reliable facade, you have done the best possible job. A sloppy attempt to hide internals can however be worse than exposing the internals directly. So this statement seems to come out of nowhere, with no explanation to back it up.
  • d979b9e6b306 - true

--JesseGlick 17:38, 26 March 2008 (UTC)

• pg 14, para 4: "Linux Distributions" => "Linux distributions"
• pg 14, para 4: "Written by the same people, that have simply been": This text is confusing. I think you mean something like "These distributions contain a common set of libraries and applications that have simply been taken..."
• pg 14, para 4: "the central management utilities": delete "the"
• (spelling) pg 14, para 4: "vendoers" => "vendors"
• pg 14, para 4: "lower, the cost": delete comma
• pg 14, para 4: "FreeBSD unix distribution" => "FreeBSD Unix distribution"
• pg 14, last para: "the open-source movement and its liberal" => "the open-source movement with its liberal"
• pg 15, para 1: "long time developers" => "long-time developers"
• pg 15, para 1: "we have the better" => "we have, the better"

--AdamDingle 23:41, 27 March 2008 (UTC)

• I disagree with Adam who says it should be "FreeBSD Unix". For consistency with the use of UNIX in the previous paragraph and with FreeBSD's Web site, it should be "UNIX". However, it probably needs to have a (R) symbol behind it, because UNIX is a registered trademark. I believe The Open Group still owns it, but I could be wrong.

--TomWheeler Thu Mar 27 21:23:09 CDT 2008

• Both "Unix" and "UNIX" are in common use; see e.g. http://en.wikipedia.org/wiki/Unix. But Tom made good points about consistency between paragraphs and with the FreeBSD site, so I now agree it should be UNIX. I have no opinion about the (R) symbol; someone would presumably need to research that.

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

• Good writing in this section
• Semicolon after "infrastructure"
• Page 14, para 4: "Written by the same people" doesn't make sense
• Page 14, para 4: "vendoers" -> "vendors"
• Page 14, para 4: No comma after "lower,"
• Page 14, para 4: "let's note" seems casual and out-of-place
• Last sentence: I don't think you need to mention that this is one of the main motivations behind the writing of this book. If it's important to API design, and since you're writing the book, this is already sufficiently demonstrated!  :)

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

AndreiBadea: Mention also dpkg next to rpm

---

Regarding dep autodiscovery by rpmbuild, I should point out that Nix is capable of doing "hard" dependency discovery: it is (nearly) impossible to build a package until all its build-time dependencies are enumerated; and it is possible to inspect most build products (ELF, ZIP, text formats) to determine which run-time dependencies it contains (since dependencies must be specified by file paths and these contain distinctive "signatures"). If you have never read about Nix, I would strongly recommend doing so, as it is a rather novel system that gets a lot of things related to APIs right that no other system really handles (at least at the operating system scale).

Regarding "classpath hell", note that Maven automates the calculation of the transitive dependency list of a component, and retrieves those dependencies. Of course you may need to worry that the list of dependencies has become physically too big. As an example, the Hudson build server freely uses a number of libraries available in Maven repositories, so its transitive dependency list is quite large - many megabytes - all of which gets dumped in the WAR you install, which could be a problem for people downloading from a slow connection. It is not clear whether all of these deps are even potentially loaded at runtime. It seems to be common for people to write a library which has some optional interactions with other libraries, but package it all together and declare hard deps on those other libraries. Clearly they should have factored the dependencies out into "bridge" packages, but most people seem to be too lazy to do so.

--JesseGlick 17:57, 26 March 2008 (UTC)

• I also thought that Maven and/or Ivy deserve a mention in this section.
• pg 15, para 2: "Only then one is able" => "Only then is one able"
• pg 16, para 3: "to start such application" => "to start such an application"
• pg 16, last para: "There are well-isolated" => "These are well-isolated"
• pg 17, para 1: "teams separation" => "team separation"
• pg 17, para 1: "and still successfully compose" => "and can still successfully compose"
• pg 17, para 4: 'my class is also depending on" => "my class also depends on"
• pg 18, last para: "use dot separated" => "use a dot-separated"
• pg 19, para 3: "One can request presence" => "One can request the presence"
• pg 19, para 3: "installation of a database" => "the installation of a database"
• pg 19, para 3: "a text editor or web browser made available" => "a text editor or web browser"
• pg 19, para 3: "a specific a version" => "a specific version"
• pg 19, para 4: "recognizable numbered version" => "recognizable numbered versions"
• pg 20, para 3: "NetBeans based" => "NetBeans-based"

--AdamDingle 23:55, 27 March 2008 (UTC)

• Page 16: Suse should be SUSE, according to Novell's Web site. I think it used to be capitalized differently and maybe have an umlaut over the U years ago, but I guess they changed it.

• Page 16: Jdom should be JDOM.

• Page 19: I think the last paragraph should say something like "we call this a specification version" because the next page uses that term without previously having defined it. The different types of version numbers might otherwise be confusing for readers who are new to it.

--TomWheeler Thu Mar 27 21:23:09 CDT 2008

• page 28: In the classpath assembly nightmare section, s/prayed/wished (wished is a better word choice when not discussing religion)
• page 30: s/through out/throughout

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

• Take the quotes away from "understand", and replace the word with comprehend.
• "important, for example," -> "important. For example,"
• "How to achieve that?" - this is not worded well. Say "How can that be achieved?"
• Remove comma in "needed environment,"
• Don't use the word "assembler", use "developer" (although I understand your point about putting pieces together) - especially since you refer to computer-level assembly in the same sentence.
• Page 17, "and so on, and so on" - just one "and so on" will suffice.

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

• pg 19, para 3: "One can request presence" => "One can request the presence"
• pg 19, para 3: "installation of a database" => "the installation of a database"
• pg 19, para 3: "a text editor or web browser made available" => "a text editor or web browser"
• pg 19, para 3: "a specific a version" => "a specific version"
• pg 19, para 4: "recognizable numbered version" => "recognizable numbered versions"
• pg 20, para 3: "NetBeans based" => "NetBeans-based"

--AdamDingle 23:55, 27 March 2008 (UTC)

• Capital L in section title
• "people use dot separated" -> "people use a dot-separated"
• The font after Figure 3.2 is funny
• Page 20, para 3: Comma after "Also"

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

• p 20, para 4: "set up" => "setup"
• p 20, para 5: "such modules, needs to discover": delete comma
• p 21, para 2: "face to face or ear to ear" => "face-to-face or ear-to-ear"
• p 21, para -2 (i.e. second from end): "worrying about future" => "worrying about the future"

--AdamDingle 23:57, 27 March 2008 (UTC)

• Page 21: Maybe you should say up front that your cousin is also a software developer.
• Page 21, last paragraph: "Throw it way" should be "throw it away"

--TomWheeler Thu Mar 27 21:23:09 CDT 2008

• I think you can capitalize About in section title
• Page 21: "ear to ear" - there's no such thing! I've never heard this phrase before
• Page 21, para 4, end of para: Weird italics on "for" and "communication"

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

• "Empiristic" is a strange word; if it is a word at all then it's very rarely used. I suggest using the word "empirical" instead, and hence titling the section "Empirical Programming".

--AdamDingle 23:59, 27 March 2008 (UTC)

• I totally agree with Adam about "Empiristic" vs. "Empirical"
• Page 21, para 5: "well-behaving" should be "well-behaved"

--TomWheeler Thu Mar 27 21:23:09 CDT 2008

• I triple-agree with Adam about "Empiristic" vs. "Empirical"

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

• On page 24, your analogy between API evolution and free speech / human rights seems a bit strained. I'd probably just skip this.
• pg 23, para 3: "you firstly need" => "you first need"
• pg 23, para 4: "good documentation of how" => "good documentation about how"

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

• I agree with Adam on the human rights bit.

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