Talk:Extreme Advice Considered Harmful

From APIDesign

---

Current revision

The section "Do Not Listen To Your Elders" seems unnecessary. The point of the entire section seems to be just this: don't accept advice unquestioningly; make sure that there are reasons to substantiate it. Doesn't that seem like a completely general (and presumably self-evident) point, not just in API design but in life in general?

--AdamDingle 16:18, 20 April 2008 (UTC)

I'd argue that the "Do Not Listen" section does have a point (and, as Adam mentioned, one that serves as a lifelong lesson as well); it can definitely be shortened, but I think it's okay to keep in a 1-to-2-paragraph version.

--Dmkoelle 02:47, 21 April 2008 (UTC)

"deprecations decrease coolness" - I'm slightly uncomfortable with this because (1) I'm not used to seeing the word "deprecated" in this form; (2) deprecated code is not the only problem an API can suffer; (3) "decrease" seems like the wrong word, I'd use "detract from", since coolness is not measurable.

Additionally, in "time to market much", I think you mean: "time to market" much -- and since time-to-market is a comfortable term, I'd suggest losing the quotation marks.

--Dmkoelle 02:50, 21 April 2008 (UTC)

Done: 98a0d282ead1

Done: 6c71b0b89bc9

I completely agree that Java should have methods which can read an entire file into a string or read lines of a file as an enumeration. I agree that the java.io.File class would be a good place for these methods, or they could appear in some I/O utility class somewhere. I agree that methods like these are incredibly useful, that these methods should have been added 10 years ago, and that they should be added today.

But I think that these methods are a strange example for your point in this section, which is that an API has to be "correct". You say in the second-to-last paragraph that these methods "might not be absolutely correct", which seems odd to me. If these methods were added, they would be correct: they would perform the task they are intended to perform. Some of them might not be appropriate or efficient for use in every case - such as with a large file - but it's normal to expect programmers to understand the performance characteristics of any method in any API. So I think that either the term "correct" isn't the right word for what you're trying to describe in this section, or that you should choose a different example.

--AdamDingle 16:47, 20 April 2008 (UTC)

I didn't understand the second paragraph of this section - I just can't visualize what you are postulating.

I need to agree with Adam here: File.asBytes(), etc. doesn't point to the API being incorrect. An incorrect API would be like one that promises to read data from XML, then fails at this task - or, fails at some edge-case, like it doesn't save enumerations correctly, or it doesn't handle nil vs. null values correctly. I guess that's a very XML-specific example (and not even a real-world one), but I can't think of an API that is NOT correct. Would be an interesting investigation to find one, though!

UPDATE TO COMMENT: I think what you're getting at through the examples you gave is, "An API Requires Well-Defined Use Cases". I'm not sure if that's missing from this section, or if it's too late to be thinking about requirements in Part III, or if you feel is covered sufficiently in other sections. Maybe it would be more appropriate to say, "An API Needs to Conform to Well-Defined Use Cases", which, like the other concepts in this chapter, is evident in a post-facto review of the API.

--Dmkoelle 02:58, 21 April 2008 (UTC)

The asLines, etc. constructs are not in the C# language, but in the .NET class library. Any .NET language can make use of them, not only C#.

--AndreiBadea 08:54, 23 April 2008 (UTC)

"the holy trinity of 'pull, merge, push' again" -- a CVS user might ask how this is different from "update, merge, commit"

• you do not need to update if someone modifies a file on different end of the universe. neither in CVS, neither in SVN

"They said that, compared to the producer of C#, Sun is committed to compatibility." This sounds like an unnecessary poke at Microsoft. I'd be OK with that if it is warranted -- and often it is -- but Microsoft has done quite well with backwards compatibility in many cases. As a matter of fact, I know several companies are still running original DOS binaries from the mid-80s on modern PCs running Windows XP and that modern versions of Excel can still open spreadsheets from fifteen years ago. In fact, I would say their backwards compatibility is one of the main things that prevents their software (operating systems especially) from really evolving.

--TomWheeler Wed Apr 23 20:38:48 CDT 2008

Perhaps you have to define correctness. I don't understand how java.io.File.asString() would not be "correct". --Richunger 02:47, 24 April 2008 (UTC)

Done: 80237ec08742

You say that "the GNOME file chooser dialog is optimized for newcomers, while being too limited for power users. .. even something as simple as using the keyboard to type a filename, is impossible". This may or may not have been true when Torvalds issued his email complaining about GNOME, but today (in, say, GNOME 2.20.1 in Ubuntu 7.10) the GNOME file chooser certainly allows a user to type a file name. To see this, start gedit, choose File/Open, then type the name of any file in the directory which the file chooser displays.

Torvalds's primary complaints at that time revolved around mouse button configurability and the printing dialog, so it might be better to focus your text on those issues.

• But my own bitter experience relates only to file dialog. I am not crazy to open gnome's print settings one. I'd rather print to pdf file and then re-print from KDE.

--AdamDingle 16:54, 20 April 2008 (UTC)

"Make the simple things easy, while making the complex things possible" - this quote is attributable to someone, isn't it? Don Norman, perhaps?

Good UI vs good API designer: I strongly disagree with you here! I think a good UI designer and a good API designer share a lot of the same qualities - they pay attention to how people think, they are capable of communicating ideas and processes through a machine interface, they are good at designing for progressive disclosure (i.e., simple things easy, complex things possible)... even as you say, you think these disciplines have a lot in common. I strongly believe (and can submit myself as evidence) that a good UI designer is likely to be a good API designer, and vice versa.

• Well, I am not good UI designer.

Is the email to Linus supposed to be a hyperlink? Looks like one because it's underlined. Torvalds' name is misspelled in the following paragraphs.

--Dmkoelle 03:05, 21 April 2008 (UTC)

Done: bec788274d94

"these objects now stay in 'young generation'" - I didn't understand this phrase.

"premature optimization is the root of all evil" is attributable to someone. Donald Knuth, I believe.

--Dmkoelle 03:08, 21 April 2008 (UTC)

"languages with less built-in optimizations, such as in .Net" .NET is not a language. Also, MSDN seems to prefer the ".NET" capitalization instead of ".Net".

--AndreiBadea 09:00, 23 April 2008 (UTC)

Done: ff62b69290ec

Some of the text about the API Fest game here is a slightly confusing, because the reader hasn't yet read the chapter about that game and doesn't know, for example, what it means to exploit an API in that game.

In the section "Sneaking Everything Into The One Percent", the text "one does not try to write factorial" is confusing: you are referring to the fact that an API user might subclass Arithmetica and override the sumTwo method to multiply rather than add, but that will not be at all obvious to most readers.

--AdamDingle 16:59, 20 April 2008 (UTC)

"Bugfixes are the sole reason for an upgrade." I guess it defines on how you describe "bug" and how you describe "upgrade." I upgraded from NetBeans 4.x to 5.x because of Matisse and API support. I upgraded to 6.x for the improved editor. These things weren't bugs, IMHO.

--TomWheeler Wed Apr 23 20:38:48 CDT 2008

Done: b9bb4d8dabdc

I would argue that this could equally be called, "An API Needs To Be Poetic"!

What you describe as symmetry, I see as poetry. We both agree that we're talking about consistency, with a touch of something slightly more appealing. A beautiful consistency, perhaps.

• Nice, but I stick with symmetry. I do not know much English poetry and I could be misinterpreted, I am afraid.

--Dmkoelle 03:14, 21 April 2008 (UTC)

"In the case of writing, you have a _live_ set of objects..." --Richunger 02:48, 24 April 2008 (UTC)