From db0a6de8995670de1a002e80acf87d3fa523c4e1 Mon Sep 17 00:00:00 2001 From: Rob Landley Date: Wed, 1 Jan 2014 14:55:53 -0600 Subject: 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. --- www/design.html | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) (limited to 'www/design.html') 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.)

-

Fast

 +

Speed

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.

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.

-

Small

 +

Size

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.

@@ -191,7 +191,22 @@ worth it.)

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.)

+understand.

+ +

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.

+ +

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.

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.

-

Joel Spolsky argues against throwing code out and starting over, 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?

Portability issues

Platforms

 -

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.

+

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.

I don't do windows.

-- cgit v1.2.3