Talk:The Art of Building Modern Software

From APIDesign

---

Revision as of 05:20, 14 June 2008

• "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)