From 4e7db256878bbf2058fa7d1bf07ddbe1c7206103 Mon Sep 17 00:00:00 2001
From: Dirk Dougherty <ddougherty@google.com>
Date: Tue, 5 Jan 2010 17:03:39 -0800
Subject: [PATCH] SDK doc change: add "Optimizing Judiciously" excerpt to best
 practices. Clean up blockquote usage in other files.

Bug: 2160782
Change-Id: I537194ecddc53d4f0e8456ce958ae8db6f521593
---
 .../android/provider/ContactsContract.java    |  44 ++---
 docs/html/guide/appendix/faq/commontasks.jd   |   6 +-
 docs/html/guide/developing/tools/adb.jd       |   4 +-
 .../guide/practices/design/performance.jd     | 175 ++++++++++++++++++
 .../practices/ui_guidelines/menu_design.jd    |   8 +-
 .../guide/topics/resources/resources-i18n.jd  |   6 +-
 docs/html/resources/faq/commontasks.jd        |   6 +-
 7 files changed, 210 insertions(+), 39 deletions(-)

diff --git a/core/java/android/provider/ContactsContract.java b/core/java/android/provider/ContactsContract.java
index c3b0f1c91faa3..a56bb4593ba23 100644
--- a/core/java/android/provider/ContactsContract.java
+++ b/core/java/android/provider/ContactsContract.java
@@ -48,49 +48,49 @@ import java.io.InputStream;
  * ContactsContract defines an extensible database of contact-related
  * information. Contact information is stored in a three-tier data model:
  * </p>
- * <blockquote>
- * <p>
+ * <ul>
+ * <li>
  * The {@link Data} table contains all kinds of personal data: phone numbers,
  * email addresses etc. The list of data kinds that can be stored in this table
  * is open-ended. There is a predefined set of common kinds, but any application
  * can add its own data kinds.
- * </p>
- * <p>
+ * </li>
+ * <li>
  * A row in the {@link RawContacts} table represents a set of Data describing a
  * person and associated with a single account.
- * </p>
- * <p>
+ * </li>
+ * <li>
  * A row in the {@link Contacts} table represents an aggregate of one or more
  * RawContacts presumably describing the same person.
- * </p>
- * </blockquote>
+ * </li>
+ * </ul>
  * <p>
  * Other tables include:
  * </p>
- * <blockquote>
- * <p>
+ * <ul>
+ * <li>
  * {@link Groups}, which contains information about raw contact groups - the
  * current API does not support the notion of groups spanning multiple accounts.
- * </p>
- * <p>
+ * </li>
+ * <li>
  * {@link StatusUpdates}, which contains social status updates including IM
  * availability.
- * </p>
- * <p>
+ * </li>
+ * <li>
  * {@link AggregationExceptions}, which is used for manual aggregation and
  * disaggregation of raw contacts
- * </p>
- * <p>
+ * </li>
+ * <li>
  * {@link Settings}, which contains visibility and sync settings for accounts
  * and groups.
- * </p>
- * <p>
+ * </li>
+ * <li>
  * {@link SyncState}, which contains free-form data maintained on behalf of sync
  * adapters
- * </p>
- * <p>
- * {@link PhoneLookup}, which is used for quick caller-ID lookup</id>
- * </blockquote>
+ * </li>
+ * <li>
+ * {@link PhoneLookup}, which is used for quick caller-ID lookup</li>
+ * </ul>
  */
 @SuppressWarnings("unused")
 public final class ContactsContract {
diff --git a/docs/html/guide/appendix/faq/commontasks.jd b/docs/html/guide/appendix/faq/commontasks.jd
index e88a8672e98a8..107199a0944c5 100644
--- a/docs/html/guide/appendix/faq/commontasks.jd
+++ b/docs/html/guide/appendix/faq/commontasks.jd
@@ -160,11 +160,9 @@ It is not necessary to put external JARs in the assets folder.
     <li>Create an {@link android.app.AlertDialog app.AlertDialog} class </li>
     <li>Set the {@link android.R.style#Theme_Dialog} <em>theme</em> attribute to <code>&#064;android:style/Theme.Dialog</code>
         in your AndroidManifest.xml file. For example:    
-</ul>
-<blockquote>
     <pre>&lt;activity class=&quot;AddRssItem&quot; android:label=&quot;Add an item&quot; android:theme=&quot;&#064;android:style/Theme.Dialog&quot;/&gt;
-</pre>
-</blockquote>
+</pre></li>
+</ul>
 <p>Calling startActivity() or startActivityForResult() will open a new screen in whatever
     way it defines itself (if it uses a floating theme it will be floating,
     otherwise it will be full screen). </p>
diff --git a/docs/html/guide/developing/tools/adb.jd b/docs/html/guide/developing/tools/adb.jd
index e8c726f8cdc91..dd60a3cc2c46a 100644
--- a/docs/html/guide/developing/tools/adb.jd
+++ b/docs/html/guide/developing/tools/adb.jd
@@ -83,12 +83,12 @@ page.title=Android Debug Bridge
 
 <p>The server then sets up connections to all running emulator/device instances. It locates emulator/device instances by scanning odd-numbered ports in the range 5555 to 5585, the range used by emulators/devices. Where the server finds an adb daemon, it sets up a connection to that port. Note that each emulator/device instance acquires a pair of sequential ports &mdash; an even-numbered port for console connections and an odd-numbered port for adb connections. For example: </p>
 
-<blockquote>
+<p style="margin-left:2em">
 Emulator 1, console: 5554<br/>
 Emulator 1, adb: 5555<br>
 Emulator 2, console: 5556<br>
 Emulator 2, adb: 5557 ...
-</blockquote>
+</p>
 
 <p>As shown, the emulator instance connected to adb on port 5555 is the same as the instance whose console listens on port 5554. </p>
 
diff --git a/docs/html/guide/practices/design/performance.jd b/docs/html/guide/practices/design/performance.jd
index 1eef34234e6bc..ec34ac9c5366d 100644
--- a/docs/html/guide/practices/design/performance.jd
+++ b/docs/html/guide/practices/design/performance.jd
@@ -22,6 +22,7 @@ actual lines of code, loops, and so on.</p>
 <p>This document covers these topics: </p>
 <ul>
     <li><a href="#intro">Introduction</a></li>
+    <li><a href="#optimize_judiciously">Optimize Judiciously</a></li>
     <li><a href="#object_creation">Avoid Creating Objects</a></li>
     <li><a href="#native_methods">Use Native Methods</a></li>
     <li><a href="#prefer_virtual">Prefer Virtual Over Interface</a></li>
@@ -74,6 +75,180 @@ of foo() is faster than bar(), then the compiled version of foo() will
 probably be as fast or faster than compiled bar(). It is unwise to rely on a
 compiler to "save" you and make your code fast enough.</p>
 
+<h2 id="optimize_judiciously">Optimize Judiciously</h2>
+
+<p>As you get started thinking about how to design your application, consider
+the cautionary points about optimization that Josh Bloch makes in his book
+<em>Effective Java</em>. Here's "Item 47: Optimize Judiciously", excerpted from
+the latest edition of the book with permission. Although Josh didn't have
+Android application development in mind when writing this section &mdash; for
+example, the <code style="color:black">java.awt.Component</code> class
+referenced is not available in Android, and Android uses the
+Dalvik VM, rather than a standard JVM &mdash; his points are still valid. </p>
+
+<blockquote>
+
+<p>There are three aphorisms concerning optimization that everyone should know.
+They are perhaps beginning to suffer from overexposure, but in case you aren't
+yet familiar with them, here they are:</p>
+
+<div style="padding-left:3em;padding-right:4em;">
+
+<p style="margin-bottom:.5em;">More computing sins are committed in the name of
+efficiency (without necessarily achieving it) than for any other single
+reason&mdash;including blind stupidity.</p>
+<p>&mdash;William A. Wulf <span style="font-size:80%;"><sup>1</sup></span></p>
+
+<p style="margin-bottom:.5em;">We should forget about small efficiencies, say
+about 97% of the time: premature optimization is the root of all evil. </p>
+<p>&mdash;Donald E. Knuth <span style="font-size:80%;"><sup>2</sup></span></p>
+
+
+<p style="margin-bottom:.5em;">We follow two rules in the matter of optimization:</p>
+<ul style="margin-bottom:0">
+<li>Rule 1. Don't do it.</li>
+<li>Rule 2 (for experts only). Don't do it yet &mdash; that is, not until you have a
+perfectly clear and unoptimized solution. </li>
+</ul>
+<p>&mdash;M. A. Jackson <span style="font-size:80%;"><sup>3</sup></span></p>
+</div>
+
+<p>All of these aphorisms predate the Java programming language by two decades.
+They tell a deep truth about optimization: it is easy to do more harm than good,
+especially if you optimize prematurely. In the process, you may produce software
+that is neither fast nor correct and cannot easily be fixed.</p>
+
+<p>Don't sacrifice sound architectural principles for performance.
+<strong>Strive to write good programs rather than fast ones.</strong> If a good
+program is not fast enough, its architecture will allow it to be optimized. Good
+programs embody the principle of <em>information hiding</em>: where possible,
+they localize design decisions within individual modules, so individual
+decisions can be changed without affecting the remainder of the system (Item
+13).</p>
+
+<p>This does <em>not</em> mean that you can ignore performance concerns until
+your program is complete. Implementation problems can be fixed by later
+optimization, but pervasive architectural flaws that limit performance can be
+impossible to fix without rewriting the system. Changing a fundamental facet of
+your design after the fact can result in an ill-structured system that is
+difficult to maintain and evolve. Therefore you must think about performance
+during the design process.</p>
+
+<p><strong>Strive to avoid design decisions that limit performance.</strong> The
+components of a design that are most difficult to change after the fact are
+those specifying interactions between modules and with the outside world. Chief
+among these design components are APIs, wire-level protocols, and persistent
+data formats. Not only are these design components difficult or impossible to
+change after the fact, but all of them can place significant limitations on the
+performance that a system can ever achieve.</p>
+
+<p><strong>Consider the performance consequences of your API design
+decisions.</strong> Making a public type mutable may require a lot of needless
+defensive copying (Item 39). Similarly, using inheritance in a public class
+where composition would have been appropriate ties the class forever to its
+superclass, which can place artificial limits on the performance of the subclass
+(Item 16). As a final example, using an implementation type rather than an
+interface in an API ties you to a specific implementation, even though faster
+implementations may be written in the future (Item 52).</p>
+
+<p>The effects of API design on performance are very real. Consider the <code
+style="color:black">getSize</code> method in the <code
+style="color:black">java.awt.Component</code> class. The decision that this
+performance-critical method was to return a <code
+style="color:black">Dimension</code> instance, coupled with the decision that
+<code style="color:black">Dimension</code> instances are mutable, forces any
+implementation of this method to allocate a new <code
+style="color:black">Dimension</code> instance on every invocation. Even though
+allocating small objects is inexpensive on a modern VM, allocating millions of
+objects needlessly can do real harm to performance.</p>
+
+<p>In this case, several alternatives existed. Ideally, <code
+style="color:black">Dimension</code> should have been immutable (Item 15);
+alternatively, the <code style="color:black">getSize</code> method could have
+been replaced by two methods returning the individual primitive components of a
+<code style="color:black">Dimension</code> object. In fact, two such methods
+were added to the Component API in the 1.2 release for performance reasons.
+Preexisting client code, however, still uses the <code
+style="color:black">getSize</code> method and still suffers the performance
+consequences of the original API design decisions.</p>
+
+<p>Luckily, it is generally the case that good API design is consistent with
+good performance. <strong>It is a very bad idea to warp an API to achieve good
+performance.</strong> The performance issue that caused you to warp the API may
+go away in a future release of the platform or other underlying software, but
+the warped API and the support headaches that come with it will be with you for
+life.</p>
+
+<p>Once you've carefully designed your program and produced a clear, concise,
+and well-structured implementation, <em>then</em> it may be time to consider
+optimization, assuming you're not already satisfied with the performance of the
+program.</p>
+
+<p>Recall that Jackson's two rules of optimization were "Don't do it," and "(for
+experts only). Don't do it yet." He could have added one more: <strong>measure
+performance before and after each attempted optimization.</strong> You may be
+surprised by what you find. Often, attempted optimizations have no measurable
+effect on performance; sometimes, they make it worse. The main reason is that
+it's difficult to guess where your program is spending its time. The part of the
+program that you think is slow may not be at fault, in which case you'd be
+wasting your time trying to optimize it. Common wisdom says that programs spend
+80 percent of their time in 20 percent of their code.</p>
+
+<p>Profiling tools can help you decide where to focus your optimization efforts.
+Such tools give you runtime information, such as roughly how much time each
+method is consuming and how many times it is invoked. In addition to focusing
+your tuning efforts, this can alert you to the need for algorithmic changes. If
+a quadratic (or worse) algorithm lurks inside your program, no amount of tuning
+will fix the problem. You must replace the algorithm with one that is more
+efficient. The more code in the system, the more important it is to use a
+profiler. It's like looking for a needle in a haystack: the bigger the haystack,
+the more useful it is to have a metal detector. The JDK comes with a simple
+profiler and modern IDEs provide more sophisticated profiling tools.</p>
+
+<p>The need to measure the effects of attempted optimization is even greater on
+the Java platform than on more traditional platforms, because the Java
+programming language does not have a strong <em>performance model</em>. The
+relative costs of the various primitive operations are not well defined. The
+"semantic gap" between what the programmer writes and what the CPU executes is
+far greater than in traditional statically compiled languages, which makes it
+very difficult to reliably predict the performance consequences of any
+optimization. There are plenty of performance myths floating around that turn
+out to be half-truths or outright lies.</p>
+
+<p>Not only is Java's performance model ill-defined, but it varies from JVM
+implementation to JVM implementation, from release to release, and from
+processor to processor. If you will be running your program on multiple JVM
+implementations or multiple hardware platforms, it is important that you measure
+the effects of your optimization on each. Occasionally you may be forced to make
+trade-offs between performance on different JVM implementations or hardware
+platforms.</p>
+
+<p>To summarize, do not strive to write fast programs &mdash; strive to write
+good ones; speed will follow. Do think about performance issues while you're
+designing systems and especially while you're designing APIs, wire-level
+protocols, and persistent data formats. When you've finished building the
+system, measure its performance. If it's fast enough, you're done. If not,
+locate the source of the problems with the aid of a profiler, and go to work
+optimizing the relevant parts of the system. The first step is to examine your
+choice of algorithms: no amount of low-level optimization can make up for a poor
+choice of algorithm. Repeat this process as necessary, measuring the performance
+after every change, until you're satisfied.</p>
+
+<p>&mdash;Excerpted from Josh Bloch's <em>Effective Java</em>, Second Ed.
+(Addison-Wesley, 2008).</em></p>
+
+<p style="font-size:80%;margin-bottom:0;"><sup>1</sup> Wulf, W. A Case Against
+the GOTO. <em>Proceedings of the 25th ACM National
+Conference</em> 2 (1972): 791–797.</p>
+<p style="font-size:80%;margin-bottom:0;"><sup>2</sup> Knuth, Donald. Structured
+Programming with go to Statements. <em>Computing
+Surveys 6</em> (1974): 261–301.</p>
+<p style="font-size:80%"><sup>3</sup> Jackson, M. A. <em>Principles of Program
+Design</em>, Academic Press, London, 1975.
+ISBN: 0123790506.</p>
+
+</blockquote>
+
 <a name="object_creation"></a>
 <h2>Avoid Creating Objects</h2>
 
diff --git a/docs/html/guide/practices/ui_guidelines/menu_design.jd b/docs/html/guide/practices/ui_guidelines/menu_design.jd
index 518cea139cd52..ebf8a4b237b23 100644
--- a/docs/html/guide/practices/ui_guidelines/menu_design.jd
+++ b/docs/html/guide/practices/ui_guidelines/menu_design.jd
@@ -93,10 +93,10 @@ page.title=Menu Design Guidelines
 
 <h2 id="tour_of_the_menus">Tour of the Menus</h2>
 
-<blockquote>
-  <b>NOTE</b> - Your menus and screens might not look like those shown in this document;
-  they may vary from one version of Android or device to another.
-</blockquote>
+<p class="note"><strong>Note:</strong> Your menus and screens might not look 
+like those shown in this document; they may vary from one version of Android 
+or device to another.
+</p>
 
 <h3 id="options_menu">Options Menu</h3>
 
diff --git a/docs/html/guide/topics/resources/resources-i18n.jd b/docs/html/guide/topics/resources/resources-i18n.jd
index 091bc62bc15a2..0c7baa17aed36 100755
--- a/docs/html/guide/topics/resources/resources-i18n.jd
+++ b/docs/html/guide/topics/resources/resources-i18n.jd
@@ -643,14 +643,14 @@ resource qualifiers in the table above.</p>
 <p>Android will pick which of the various underlying resource files should be
 used at runtime, depending on the current configuration of the device.
 The example used here assumes the following device configuration:</p>
-<blockquote>
-  <p>Locale = <code>en-GB</code><br>
+
+  <p style="margin-left:2em">Locale = <code>en-GB</code><br>
   Screen orientation = <code>port</code><br>
   Screen pixel density = <code>mdpi</code><br>
     Touchscreen type = <code>notouch</code><br>
     Primary text input method = <code>12key</code><br>
   </p>
-</blockquote>
+
 <p>Here is how  Android  makes the selection: </p>
 <ol>
     <li>
diff --git a/docs/html/resources/faq/commontasks.jd b/docs/html/resources/faq/commontasks.jd
index fa487f7f0361c..2f09b0019fd96 100644
--- a/docs/html/resources/faq/commontasks.jd
+++ b/docs/html/resources/faq/commontasks.jd
@@ -160,11 +160,9 @@ It is not necessary to put external JARs in the assets folder.
     <li>Create an {@link android.app.AlertDialog app.AlertDialog} class </li>
     <li>Set the {@link android.R.style#Theme_Dialog} <em>theme</em> attribute to <code>&#064;android:style/Theme.Dialog</code>
         in your AndroidManifest.xml file. For example:    
+    <pre>&lt;activity class=&quot;AddRssItem&quot; android:label=&quot;Add an item&quot; android:theme=&quot;&#064;android:style/Theme.Dialog&quot;/&gt;</pre></li>
 </ul>
-<blockquote>
-    <pre>&lt;activity class=&quot;AddRssItem&quot; android:label=&quot;Add an item&quot; android:theme=&quot;&#064;android:style/Theme.Dialog&quot;/&gt;
-</pre>
-</blockquote>
+
 <p>Calling startActivity() or startActivityForResult() will open a new screen in whatever
     way it defines itself (if it uses a floating theme it will be floating,
     otherwise it will be full screen). </p>