Talk:The Art of Building Modern Software

From APIDesign

• "It has been less than one hundred years since people wrote and managed to execute the first computer program"
  • Remove "managed to", and change "execute" to "executed". No need for extra verbiage.
  • Interesting that you say "It's been less than one hundred years" - that seems like a long time to me! This is probably a cultural bias.

--Dmkoelle 12:06, 28 March 2008 (UTC)

e290520a0df8 - I have expanded this section based on your comments

• Can this section be deleted please?

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

• I agree that this section is overly philosophical and recommend either greatly shortening or deleting it.
• (wording) pg. 4: "just a pure thought" => "pure thought alone"
• (wording) pg. 4: "the Galileo Galilei" => "Galileo Galilei"
• (wording) pg. 4: "he attributed that to mutual cooperation..." => "they attributed physical phenomena to the mutual cooperation..."
• (wording) pg. 4: "It was the experiment that showed..." => "It was this sort of experiment that showed..."
• (wording) pg. 4: "It was the catalyst" => "This was the catalyst"
• (wording) pg. 4: "has to be reasonable" => "has to be rational"
• (wording) pg. 4: "a reasonable origin" => "a rational origin"
• (wording) pg. 5: "the world does not need to be reasonable": perhaps "rational" instead

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

• "seing" is misspelled; it should be "seeing"
• Page 4, para 4 "think it up" seems to have an extra space. Also the period should be inside the quote (at least according to the API style guide)

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

• We're in Chapter 2, and I'm ready to talk about API Design, not philosophy. I don't think the discussion on rationalism and empiricism is going to help me think more about the fact that my methods should be named consistently.
• The page numbering is wrong here. We're not on Page 4 in the book.
• Need comma after "expectations" in "natural expectations as anyone"
• Pg 4 Para 3: Was Galileo's experiment really the first time that thought could prove observation and experience wrong? I would imagine humans have been doing this for eons.
• Pg 4 Para 3: Was this really the catalyst for rationalism?
• Pg 4 Para 4: Reword "think it up" and remove the quotes. When you need to quote some kitchy phrase, it usually means it's not properly or clearly worded.
• Pg 5 continued paragraph: change "the first scientist that" to "the first scientist who", since you're talking about a person.
• Pg 5 Para 1: Need comma between "Also Descartes"
• Pg 5 Para 1: "So for us it should not be a big problem to merge..." Why do we (or I, the reader) need to merge anything? I don't want to merge viewpoints. I want to learn the ins and outs of API design.

--Dmkoelle 12:13, 28 March 2008 (UTC)

• I agree that this is all a bit long: by this point in the book I was saying to myself "when is he going to finish with the philosophy and history and start giving concrete advice about API design?" Consider shortening.
• pg 6, "There are said to have been two schools of computer science...": What you're describing in this paragraph sounds a lot like the "worse is better" approach versus the "MIT approach". See http://en.wikipedia.org/wiki/Worse_is_better .
  • Sounds like similar story.
• pg 6: "Indeed these days nobody is seriously considering writing a new system in COBOL": This is highly debatable. According to the page http://en.wikipedia.org/wiki/Cobol, the COBOL 2002 standard adds object-oriented programming and other modern language features; it seems the language is very much alive, at least as of a few years ago.
  • I noted "new system" - for that is very likely true.
• (wording) section title: "Evolution of Software so Far" => "The Evolution of Software So Far"
• (wording) pg 5, para 5: "nor worry about technical internals" => "nor worry about the technical internals"
• (grammar) pg 5, para 5: "A huge win" => "This was a huge win" (incomplete sentence)
• (typo) pg 5, para 6: "the the appetite" => "the appetite"
• (wording) pg 5, para 6: "language readable by management" => "readable by management"
• (wording) pg 6, para 1: "things in it should be reasonable" => "things in it should be rational"
• (wording) pg 6, para 1: "having strong theoretical backend" => "having a strong theoretical foundation"
• (wording) pg 6, para 1: "really reasonable" => "mathematically sound"
• (wording) pg 6, para 2: "If it really was," => "If programming really was that,"
• (spelling) pg 6, para 2: "algoritms" => "algorithms"
• (spelling) pg 6, para 2: "never ending" => "never-ending"
• (wording) pg 6, last para: "It looks like it is time to confirm" => "It may seem that it is time to conclude"
• (wording) pg 7, para 1: "the Figure 2-1" => "Figure 2-1"
• (wording) pg 7, para 1: "quote of from Edsger" => "quote from Edsger"
• (wording) pg 7, para 1: "True, however" => "This may be true, however"
• (wording) pg 7, para 2: "a philosopher to work" => "a philosopher in order to work"
• (wording) pg 7, para 2: "a place for less educated" => "a place for the less educated"
• (wording) pg 7, para 2: "the more clueless of us" => "the more clueless among us"
• (wording) pg 7, para 2: "still things seem to work" => "things still seem to work"
• (spelling, wording) pg 7, para 2: "software enginering[SP] shall not need" => "software engineering should not require"
• (wording) pg 7, para 2: "to be highly educated scientist" => "to be a highly educated scientist"
• (wording) pg 7, para 3: "on the keyboard" => "on a keyboard"
• (wording) pg 7, para 3: "just like ability to watch" => "just as the ability to watch"
• (wording) pg 7, para 3: "is to make the programmers know less" => "is to make programmers know less"
• (wording) pg 7, para 3: "the goal is to find such coding practices" => "the goal is to find coding practices"

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

• "and in worse cases handle the screwdriver and wires that physically carried the signal" This wording makes it sound like screwdrivers were used to carry signals, which I hope was not the case!
  • 3164a98f271b
• Page 7, para 1: "Or, as the Figure 2-1 illustrates, we are running out of any programmers almost completely." I don't understand this on a couple of levels. First, HTML is not a programming language. Secondly, (ignoring the first point) the law of supply and demand says we are obviously not running out of programmers or this guy would have a job. It's an amusing picture, but I don't understand why its here.
  • Just imagine he gets the job.

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

• page 19: I'm guessing Dijkstra's quote should actually read, "...probably beyond...", not behind.
• page 19: I don't understand the comparison to TV-ad viewing as a "necessary skill among humans"
  • b1c2ae407972
• I agree with Jesse that this section, for your audience, is probably extraneous and should be removed. I think the "Putting the Web Page on the Web" anecdote at the beginning of the next section is very good and it is sufficient to draw a contrast to the bulldozer approach.

--RichUnger Thu Mar 27 20:30:09 PDT 2008

• Long and probably unnecessary, consider deleting.

--JesseGlick 03:56, 25 March 2008 (UTC)

• It's okay to uppercase "So" in the title, since it's part of the phrase "So Far" (compare and contrast with something like, "Doing the Work so You Don't Have To")
• Need comma after "early fifties"
• Change "worse cases" to "the worst case"
• I would advise against the word "slavery", which could be disturbing to some American readers
• I would advise against the word "boring" when describing mechanical jobs
• Grammar: I see this a lot in the text, so I'm going to make my final stand here: When used to introduce a sentence, words like "However", "Regardless", "Similarly", "Surprisingly", etc. need to be followed with a comma!
• "However in those days COBOL" --> "However, in those days, COBOL"
• "theoretical backend" --> "theoretical back-end"
• Why is Dijkstra's name in italics?
• Need to fix the reference to book.dijkstra
• Capitalize "Programming" in Dijkstra's quote
• Need a comma after "etc." in "hospital patient databases, etc."
• Don't use etc. when referring to Wirth's inventions - say something like, "and other languages" or something; etc. implies that the reader can complete the thought in their own head, which in this case I doubt many could.
  • 1f8962f27a61
• "approach has no space" --> "approach has no place"
• I'm not sure how the photo shows that we are running out of programmers
• The first instance of the word "clueless" - Page 7, Para 2 - doesn't make sense, until one reads your definition of "clueless" later on. Please define it here; otherwise, it sounds offensive.

--Dmkoelle 12:15, 28 March 2008 (UTC)

On this section, I disagree with Jesse. It's only one page, and I think it communicates a very important concept which you refer to in the rest of the book. Also, I recently interviewed with Amazon, for a job on their "open source" team. They definitely make very heavy use of off-the-shelf packages, both for infrastructure (apache, tomcat, etc) and libraries. Each team has a great deal of latitude in selecting OSS libraries for their own project.

• page 20: s/way time-consuming/way more time-consuming

--RichUnger Thu Mar 27 20:50:09 PDT 2008

Contributes little to the book, should be reduced.

What makes you think Amazon uses "bulldozer" coding? Surely they use a certain amount of off-the-shelf software, but I imagine they put a lot of effort into customized software to replace what would otherwise be too inefficient for their massive needs.

--JesseGlick 04:03, 25 March 2008 (UTC)

• (wording) pg 8, para 3: "is that bad?" => "is that bad."
• (wording) pg 8, para 3: "gigantic sites, which work": delete comma

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

• Page 7, para 4 "enginering" should be "engineering"
• Page 7, para 5 "incomming" should be "incoming"

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

• "two choices - either" --> "two choices. I could either"
• "incomming" --> "incoming"
• "I needed an additional feature" --> "I needed additional features"
• Delete "However" in last sentence of Page 7, para 6
• Page 7/8, "Then on top of that..." is not a complete sentence
• "At that point this is an easy task" - awkward, too many that's and this's. Rephrase.
• "In fact" needs to be followed by a comma
• Page 8, para 3 - remove question mark from first sentence - you're not actually asking the question, you're posing it as something to consider.
• "Amazon, Yahoo, etc. are gigantic sites, which work surprisingly well" - I would advise removing "surprisingly", it discounts the many hours of work that went into these sites
  • 9042d9c78050

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

• Relativistic geometry is no less geometrical, and certainly no less "beautiful", than Euclidean. Simply a different set of equations.
  • True, from today's perspective. However everyone who believes that a square is more beautiful than rectangle has to still consider Euclidean geometry more beautiful. The others do not have squares.

This section is very long-winded and most of it could be deleted without any real effect on its arguments.

--JesseGlick 04:16, 25 March 2008 (UTC)

• This section is philosophical and long-winded and not very relevant. I recommend deleting it in its entirety.

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

I agree that this section reads more like a philosophical treatise. I think the first paragraph is important. You are probably correct about your readers' reaction to the previous section, and it's good to address it. However, I think the next section (More Cluelessness!) does a better job of being a convincing argument.

• page 20: s/layed down/laid down

--RichUnger Thu Mar 27 20:50:09 PDT 2008

• layed --> laid
• I agree with the above comments that recommend deleting this philosophical section
• Enigma movie: I don't know what the Enigma movie is. Also, extra space after "His answer: (quote)"

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

• (wording) pg 10, para 5: "without full understanding" => "without a full understanding"
• (wording) pg 11, para 1: "understand chemistry to clean" => "understand chemistry in order to clean"
• (grammar) pg 11, para 5: "Indeed, a horrible vision" => "This is indeed a horribly vision" (incomplete sentence)
• (wording) pg 11, para 6: "slightly also program verification" => "slightly also on program verification"
• (wording) pg 11, para 6: "while still produce" => "while still producing"
• (wording) pg 11, para 7: "There can be shallow understanding" => "There can be a shallow understanding"
• (wording) pg 11, para 7: "and deep understanding" => "and a deep understanding"
• (wording) pg 11, para 7: "we need only shallow understanding" => "we need only a shallow understanding"
• (wording) pg 11, para 7: "people who repair the clocks, or cars, or TVs, needs to have much wider" => "people who repair clocks, cars or TVs need to have a much wider"
• (wording) pg 11, para 7: "even those people need only shallow" => "even those people need only a limited"
• (spelling) pg 11, para 8: "sence" => "sense"
• (wording) pg 11, para 8: "rely only on shallow" => "rely only on a shallow"
• (spelling, wording) pg 12: "throughfully positive term" => "a thoroughly positive term"

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

• "If we need to use a television, we do not need a deep understanding of the problem." No problem was defined. I think you should rephrase this more like "If we need to use a television, we do not need a deep understanding of how televisions actually work."
  • ae6d86ef3580

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

I think the analogies used here are misleading. It is true that you do not need to know much about how a car works to drive; it is generally economically feasible to drive until it breaks, then pay someone competent to fix it. Similarly, you can send and receive email knowing next to nothing about SMTP and IMAP and so forth; when your program breaks, just try a different one and hope for the best.

• • 67350e7e359b

But "using" an API is inherently different from "using" a consumer product. Most usages are in fact stretching the original design parameters, and in practice quite a lot of time this breaks. Paying someone else to fix it on your behalf is often not economical; by trying to use something you don't really understand, a novice programmer can subtract value rather than add it. This is nicely argued in The Law of Leaky Abstractions.

• • Misuse of API is addressed in another chapter.

--JesseGlick 04:29, 25 March 2008 (UTC)

• "We have seen that..." - I'm not sure this was adequately proven
• Page 10, para 6 - why is 'bulldozer' colored?
• Page 11, para 2 - this short paragraph is all awkwardly worded. Rephrase.
• "at OOPSLA" --> "at the OOPSLA"
• Put quotations around Minimizing ... Software Systems
• "can handle only a limited amount of data and that if the" --> "and can handle only a limited amount of data. If the"
• "In his presentation" COMMA
• "slightly also" is not a phrase. Remove it, or replace with "to some degree"
• Page 11, para beginning "The term cluelessness" - I think there are too many examples in this paragraph. After the first example, I get it.
• "sence" -> "sense"
• "is throughfully positive term" - "is A THOROUGHLY positive term"

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

Beauty (or something like it matters) a lot

OK on page 10 of the API book you take up a very interesting and important question- does beauty (in code) matter? I won't detail everything you say there, but one point you make is that it's more important to faciliate time-to-market for developers than beauty. This is achieved through cluelessness- which I understand as developing an API which minimizes the number of things a developer has to know to use it productively.

I hope I represented that correctly.

Here's why I think beauty, or coding clarity, matters a lot.

Let's say you're right- developers care most about turning around code fast and getting it to market. And let's agree that developers want to remain as clueless as possible. A reasonable developer (ok ... myself) could (ok.. did) go through the following chain of reasoning and conclude that an available API (ok.. yours-Lookup) should not be used, and instead, the same functionality should be written from scratch if at all possible.

If the developer ships a product using an API, then that developer inherits the API code's functionality but also the responsibility for the API code's functioning, at least as far as his customers are concerned.

One consequence of this is that if the API is found wanting for any reason, say it's the source of some subtle bug or it's identified as a performance liability, the developer is responsible for fixing it.

But if the code underlying the API is not beautiful (== clear == easily understandable), then the developer is in a sorry situation. The "quick win" of leveraging the API code has turned into an even bigger liability. Instead of facing a code base that the developer wrote and therefore understands and can fix, the developer is facing a codebase that is not beautiful, not easy to understand and instead of facilitating rapid code is now inhibiting it.

What's worse is, the time frame in which results are expected is shorter (critical bug) and it's directly affecting / losing customers as opposed to the downside of getting to market more slowly.

The developer is faced with a terrible choice- spend inordinate amounts of time trying to understand and debug foreign, non-beautiful code or rewrite the same functionality from scratch, breaking all the developer's API consumers in the process.

Now cluelessness plays into this in another way. The API originator may naturally feel that whatever has gone wrong, it's NOT the API's fault. Let's suppose the API originator is right. The developer's desire for cluelessness, for not wanting to know the source code well - leads the developer to take the attitude, however misguided or ill-informed, that the API is suspect. Cluelessness in this context means the API never gets a fair trial ! The developer wants to remain clueless about the API and the API is written in a way that encourages cluelessness, so now cluelessness is working against API adoption and the developer.

Finally, the mere fact that the above could happen is enough to make the circumspect developer decide against using the API. If a codebase is not comprehensible with easy (a new, better definition of clueless in my view) study, then it can't be included in a product unless there really is absolutely no choice; so JDK6 gets in, for instance, since it's just not possible to re-write that.

Comprehensibility of source code is paramount if a developer is going to be responsible to customers for the proper functioning of that source code.

I alluded to the fact that this was an actual case and it was. I could not confirm that Lookup's frequent use of casting, instanceof and reflection was not responsible for the perceived slowness of Lookup as judged by the slowness I feel when using Netbeans where I suspect Lookup is being used extensively.

Ouch!! How do you like that for vague suspicions! That's not fair, and yet, isn't that exactly my point? I want to remain clueless, that is, not exert too much time and effort for too long over this API. So this is how cluelessness plays out in my game-theory flavored analysis of the question- should I use this API?

Sorry to say, but all code has to face its day in my kangaroo court where guilt by association constitutes plenty of good evidence and statistical false positives have all the credit in the world - I just can't afford to be caught in the above scenario vis-a-vis my customers and my reputation.

The only way to prove you're not guilty to the crooked judge before you is to make it as easy as possible for me to understand the sourcecode so I gain confidence in it.

But your definition of cluelessness militates against that, while mine- the sourcecode is easy to understand - would ensure the API gets a fair trial.

We should strive for code clarity. If that conflicts with API writing, and you've convinced me it does, then that's a standoff between two equal claims and needs to be reconciled through other means.

In my code, I have annotations that I arrogantly call infallibilityReasons. They represent shorthand reasons why a given method cannot fail (short of a VM, etc. failure) the way the laws of logic do in a proofs. They represent a shorthand way for the reader to gain clarity and confidence in the code.

What coders need are more and better ways to demonstrate - through whatever means - the intent and rightness of their code, not in the strictest sense- which we all know is not possible- but in the human sense.

Of course, it's not a coincidence that I have lots of ideas for extending editors to support this kind of thing, having wrestled with this issue for a long time now and you can probably take some satisfaction in the irony that any such extension would take the form of a netbeans plugin, which necessitates the understanding of the very API I just got done dissing (not really !).

--68.57.243.125 16:38, 10 April 2009 (UTC)swv