Add new paragraphs on trading off different _kinds_ of simplicity (easy for machine to run vs easy for humans to follow), and why comments aren't a substitute for good code.

1 files changed, 23 insertions, 8 deletions

diff --git a/www/design.html b/www/design.html
index ce5fc55b..dc0bea21 100755
--- a/www/design.html
+++ b/www/design.html
@@ -32,7 +32,7 @@ use case is to download a statically linked toybox binary to an arbitrary
 Linux system, and use it in an otherwise unknown environment; being
 self-contained helps support this.)</p>
 
-<b><h3>Fast</h3></b>
+<b><h3>Speed</h3></b>
 
 <p>It's easy to say lots about optimizing for speed (which is why this section
 is so long), but at the same time it's the optimization we care the least about.
@@ -141,7 +141,7 @@ give at least a reasonable result.</p>
 applies to toybox.  Do the simple thing first, do as little of it as possible,
 and make sure it's right.  You can always speed it up later.</p>
 
-<b><h3>Small</h3></b>
+<b><h3>Size</h3></b>
 <p>Again, simple gives you most of this.  An algorithm that does less work
 is generally smaller.  Understand the problem, treat size as a cost, and
 get a good bang for the byte.</p>
@@ -191,7 +191,22 @@ worth it.)</p>
 
 <p>Simplicity has lots of benefits.  Simple code is easy to maintain, easy to
 port to new processors, easy to audit for security holes, and easy to
-understand.  (Comments help, but they're no substitute for simple code.)</p>
+understand.</p>
+
+<p>Simplicity itself can have subtle non-obvious aspects requiring a tradeoff
+between one kind of simplicity and another: simple for the computer to
+execute and simple for a human reader to understand aren't always the
+same thing. A compact and clever algorithm that does very little work may
+not be as easy to explain or understand as a larger more explicit version
+requiring more code, memory, and CPU time. When balancing these, err on the
+side of doing less work, but add comments describing how you
+could be more explicit.</p>
+
+<p>In general, comments are not a substitute for good code (or well chosen
+variable or function names). Commenting "x += y;" with "/* add y to x */"
+can actually detract from the program's readability. If you need to describe
+what the code is doing (rather than _why_ it's doing it), that means the
+code itself isn't very clear.</p>
 
 <p>Prioritizing simplicity tends to serve our other goals: simplifying code
 generally reduces its size (both in terms of binary size and runtime memory
@@ -199,7 +214,6 @@ usage), and avoiding unnecessary work makes code run faster. Smaller code
 also tends to run faster on modern hardware due to CPU cacheing: fitting your
 code into L1 cache is great, and staying in L2 cache is still pretty good.</p>
 
-
 <p><a href=http://www.joelonsoftware.com/articles/fog0000000069.html>Joel
 Spolsky argues against throwing code out and starting over</a>, and he has
 good points: an existing debugged codebase contains a huge amount of baked
@@ -229,10 +243,11 @@ programmers should strive to be lazy and dumb</a>?</p>
 <b><h2>Portability issues</h2></b>
 
 <b><h3>Platforms</h3></b>
-<p>Toybox should run on Android (alas, with bionic), and every other hardware
-platform Linux runs on.  Other posix/susv4 environments (perhaps MacOS X or
-newlib+libgloss) are vaguely interesting but only if they're easy to support;
-I'm not going to spend much effort on them.</p>
+<p>Toybox should run on Android (all commands with musl-libc, as large a subset
+as practical with bionic), and every other hardware platform Linux runs on.
+Other posix/susv4 environments (perhaps MacOS X or newlib+libgloss) are vaguely
+interesting but only if they're easy to support; I'm not going to spend much
+effort on them.</p>
 
 <p>I don't do windows.</p>