annotate www/design.html @ 1387:a0d26c5e3271 draft

Release notes for 0.4.9.
author Rob Landley <rob@landley.net>
date Mon, 07 Jul 2014 07:32:56 -0500
parents 97c7f42068b5
children 990776cf60db
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1180
94eb7b9127d2 Change header and pages so each page has its own title.
Rob Landley <rob@landley.net>
parents: 1177
diff changeset
1 <html><head><title>The design of toybox</title></head>
365
8f0b24cc7cd7 Minor web page updates (put header/footer back, add a few <hr> tags).
Rob Landley <rob@landley.net>
parents: 200
diff changeset
2 <!--#include file="header.html" -->
8f0b24cc7cd7 Minor web page updates (put header/footer back, add a few <hr> tags).
Rob Landley <rob@landley.net>
parents: 200
diff changeset
3
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
4 <b><h2>Design goals</h2></b>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
5
529
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
6 <p>Toybox should be simple, small, fast, and full featured. Often, these
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
7 things need to be balanced off against each other. In general, keeping the
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
8 code simple the most important (and hardest) goal, and small is slightly more
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
9 important than fast. Features are the reason we write code in the first
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
10 place but this has all been implemented before so if we can't do a better
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
11 job why bother? It should be possible to get 80% of the way to each goal
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
12 before they really start to fight.</p>
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
13
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
14 <p>Here they are in reverse order of importance:</p>
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
15
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
16 <b><h3>Features</h3></b>
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
17
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
18 <p>The <a href=roadmap.html>roadmap</a> has the list of features we're
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
19 trying to implement, and the reasons for them. After the 1.0 release
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
20 some of that material may get moved here.</p>
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
21
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
22 <p>Some things are simply outside the scope of the project: even though
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
23 posix defines commands for compiling and linking, we're not going to include
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
24 a compiler or linker (and support for a potentially infinite number of hardware
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
25 targets). And until somebody comes up with a ~30k ssh implementation, we're
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
26 going to point you at dropbear or polarssl.</p>
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
27
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
28 <p>Environmental dependencies are a type of complexity, so needing other
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
29 packages to build or run is a big downside. For example, we don't use curses
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
30 when we can simply output ansi escape sequences and trust all terminal
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
31 programs written in the past 30 years to be able to support them. (A common
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
32 use case is to download a statically linked toybox binary to an arbitrary
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
33 Linux system, and use it in an otherwise unknown environment; being
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
34 self-contained helps support this.)</p>
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
35
1177
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
36 <b><h3>Speed</h3></b>
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
37
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
38 <p>It's easy to say lots about optimizing for speed (which is why this section
529
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
39 is so long), but at the same time it's the optimization we care the least about.
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
40 The essence of speed is being as efficient as possible, which means doing as
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
41 little work as possible. A design that's small and simple gets you 90% of the
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
42 way there, and most of the rest is either fine-tuning or more trouble than
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
43 it's worth (and often actually counterproductive). Still, here's some
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
44 advice:</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
45
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
46 <p>First, understand the darn problem you're trying to solve. You'd think
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
47 I wouldn't have to say this, but I do. Trying to find a faster sorting
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
48 algorithm is no substitute for figuring out a way to skip the sorting step
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
49 entirely. The fastest way to do anything is not to have to do it at all,
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
50 and _all_ optimization boils down to avoiding unnecessary work.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
51
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
52 <p>Speed is easy to measure; there are dozens of profiling tools for Linux
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
53 (although personally I find the "time" command a good starting place).
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
54 Don't waste too much time trying to optimize something you can't measure,
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
55 and there's no much point speeding up things you don't spend much time doing
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
56 anyway.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
57
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
58 <p>Understand the difference between throughput and latency. Faster
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
59 processors improve throughput, but don't always do much for latency.
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
60 After 30 years of Moore's Law, most of the remaining problems are latency,
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
61 not throughput. (There are of course a few exceptions, like data compression
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
62 code, encryption, rsync...) Worry about throughput inside long-running
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
63 loops, and worry about latency everywhere else. (And don't worry too much
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
64 about avoiding system calls or function calls or anything else in the name
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
65 of speed unless you are in the middle of a tight loop that's you've already
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
66 proven isn't running fast enough.)</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
67
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
68 <p>"Locality of reference" is generally nice, in all sorts of contexts.
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
69 It's obvious that waiting for disk access is 1000x slower than doing stuff in
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
70 RAM (and making the disk seek is 10x slower than sequential reads/writes),
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
71 but it's just as true that a loop which stays in L1 cache is many times faster
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
72 than a loop that has to wait for a DRAM fetch on each iteration. Don't worry
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
73 about whether "&" is faster than "%" until your executable loop stays in L1
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
74 cache and the data access is fetching cache lines intelligently. (To
694
786841fdb1e0 Reindent to two spaces per level. Remove vi: directives that haven't worked right in years (ubuntu broke its' vim implementation). Remove trailing spaces. Add/remove blank lines. Re-wordwrap in places. Update documentation with new coding style.
Rob Landley <rob@landley.net>
parents: 616
diff changeset
75 understand DRAM, L1, and L2 cache, read Hannibal's marvelous ram guide at Ars
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
76 Technica:
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
77 <a href=http://arstechnica.com/paedia/r/ram_guide/ram_guide.part1-2.html>part one</a>,
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
78 <a href=http://arstechnica.com/paedia/r/ram_guide/ram_guide.part2-1.html>part two</a>,
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
79 <a href=http://arstechnica.com/paedia/r/ram_guide/ram_guide.part3-1.html>part three</a>,
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
80 plus this
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
81 <a href=http://arstechnica.com/articles/paedia/cpu/caching.ars/1>article on
156
1e8f4b05cb65 Remove trailing whitespace (thanks to Charlie Shepherd), and a couple comment
Rob Landley <rob@landley.net>
parents: 117
diff changeset
82 cacheing</a>, and this one on
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
83 <a href=http://arstechnica.com/articles/paedia/cpu/bandwidth-latency.ars>bandwidth
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
84 and latency</a>.
117
07d8795fc19c Link to ars technica paedia broke because ars is now using Windows 2003 on
Rob Landley <rob@landley.net>
parents: 114
diff changeset
85 And there's <a href=http://arstechnica.com/paedia/index.html>more where that came from</a>.)
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
86 Running out of L1 cache can execute one instruction per clock cycle, going
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
87 to L2 cache costs a dozen or so clock cycles, and waiting for a worst case dram
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
88 fetch (round trip latency with a bank switch) can cost thousands of
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
89 clock cycles. (Historically, this disparity has gotten worse with time,
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
90 just like the speed hit for swapping to disk. These days, a _big_ L1 cache
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
91 is 128k and a big L2 cache is a couple of megabytes. A cheap low-power
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
92 embedded processor may have 8k of L1 cache and no L2.)</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
93
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
94 <p>Learn how virtual memory and memory managment units work. Don't touch
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
95 memory you don't have to. Even just reading memory evicts stuff from L1 and L2
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
96 cache, which may have to be read back in later. Writing memory can force the
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
97 operating system to break copy-on-write, which allocates more memory. (The
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
98 memory returned by malloc() is only a virtual allocation, filled with lots of
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
99 copy-on-write mappings of the zero page. Actual physical pages get allocated
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
100 when the copy-on-write gets broken by writing to the virtual page. This
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
101 is why checking the return value of malloc() isn't very useful anymore, it
156
1e8f4b05cb65 Remove trailing whitespace (thanks to Charlie Shepherd), and a couple comment
Rob Landley <rob@landley.net>
parents: 117
diff changeset
102 only detects running out of virtual memory, not physical memory. Unless
1e8f4b05cb65 Remove trailing whitespace (thanks to Charlie Shepherd), and a couple comment
Rob Landley <rob@landley.net>
parents: 117
diff changeset
103 you're using a NOMMU system, where all bets are off.)</p>
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
104
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
105 <p>Don't think that just because you don't have a swap file the system can't
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
106 start swap thrashing: any file backed page (ala mmap) can be evicted, and
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
107 there's a reason all running programs require an executable file (they're
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
108 mmaped, and can be flushed back to disk when memory is short). And long
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
109 before that, disk cache gets reclaimed and has to be read back in. When the
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
110 operating system really can't free up any more pages it triggers the out of
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
111 memory killer to free up pages by killing processes (the alternative is the
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
112 entire OS freezing solid). Modern operating systems seldom run out of
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
113 memory gracefully.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
114
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
115 <p>Also, it's better to be simple than clever. Many people think that mmap()
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
116 is faster than read() because it avoids a copy, but twiddling with the memory
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
117 management is itself slow, and can cause unnecessary CPU cache flushes. And
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
118 if a read faults in dozens of pages sequentially, but your mmap iterates
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
119 backwards through a file (causing lots of seeks, each of which your program
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
120 blocks waiting for), the read can be many times faster. On the other hand, the
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
121 mmap can sometimes use less memory, since the memory provided by mmap
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
122 comes from the page cache (allocated anyway), and it can be faster if you're
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
123 doing a lot of different updates to the same area. The moral? Measure, then
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
124 try to speed things up, and measure again to confirm it actually _did_ speed
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
125 things up rather than made them worse. (And understanding what's really going
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
126 on underneath is a big help to making it happen faster.)</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
127
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
128 <p>In general, being simple is better than being clever. Optimization
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
129 strategies change with time. For example, decades ago precalculating a table
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
130 of results (for things like isdigit() or cosine(int degrees)) was clearly
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
131 faster because processors were so slow. Then processors got faster and grew
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
132 math coprocessors, and calculating the value each time became faster than
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
133 the table lookup (because the calculation fit in L1 cache but the lookup
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
134 had to go out to DRAM). Then cache sizes got bigger (the Pentium M has
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
135 2 megabytes of L2 cache) and the table fit in cache, so the table became
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
136 fast again... Predicting how changes in hardware will affect your algorithm
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
137 is difficult, and using ten year old optimization advice and produce
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
138 laughably bad results. But being simple and efficient is always going to
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
139 give at least a reasonable result.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
140
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
141 <p>The famous quote from Ken Thompson, "When in doubt, use brute force",
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
142 applies to toybox. Do the simple thing first, do as little of it as possible,
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
143 and make sure it's right. You can always speed it up later.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
144
1177
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
145 <b><h3>Size</h3></b>
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
146 <p>Again, simple gives you most of this. An algorithm that does less work
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
147 is generally smaller. Understand the problem, treat size as a cost, and
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
148 get a good bang for the byte.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
149
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
150 <p>Understand the difference between binary size, heap size, and stack size.
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
151 Your binary is the executable file on disk, your heap is where malloc() memory
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
152 lives, and your stack is where local variables (and function call return
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
153 addresses) live. Optimizing for binary size is generally good: executing
156
1e8f4b05cb65 Remove trailing whitespace (thanks to Charlie Shepherd), and a couple comment
Rob Landley <rob@landley.net>
parents: 117
diff changeset
154 fewer instructions makes your program run faster (and fits more of it in
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
155 cache). On embedded systems, binary size is especially precious because
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
156 flash is expensive (and its successor, MRAM, even more so). Small stack size
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
157 is important for nommu systems because they have to preallocate their stack
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
158 and can't make it bigger via page fault. And everybody likes a small heap.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
159
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
160 <p>Measure the right things. Especially with modern optimizers, expecting
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
161 something to be smaller is no guarantee it will be after the compiler's done
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
162 with it. Binary size isn't the most accurate indicator of the impact of a
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
163 given change, because lots of things get combined and rounded during
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
164 compilation and linking. Matt Mackall's bloat-o-meter is a python script
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
165 which compares two versions of a program, and shows size changes in each
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
166 symbol (using the "nm" command behind the scenes). To use this, run
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
167 "make baseline" to build a baseline version to compare against, and
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
168 then "make bloatometer" to compare that baseline version against the current
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
169 code.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
170
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
171 <p>Avoid special cases. Whenever you see similar chunks of code in more than
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
172 one place, it might be possible to combine them and have the users call shared
529
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
173 code. (This is the most commonly cited trick, which doesn't make it easy. If
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
174 seeing two lines of code do the same thing makes you slightly uncomfortable,
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
175 you've got the right mindset.)</p>
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
176
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
177 <p>Some specific advice: Using a char in place of an int when doing math
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
178 produces significantly larger code on some platforms (notably arm),
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
179 because each time the compiler has to emit code to convert it to int, do the
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
180 math, and convert it back. Bitfields have this problem on most platforms.
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
181 Because of this, using char to index a for() loop is probably not a net win,
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
182 although using char (or a bitfield) to store a value in a structure that's
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
183 repeated hundreds of times can be a good tradeoff of binary size for heap
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
184 space.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
185
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
186 <b><h3>Simple</h3></b>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
187
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 365
diff changeset
188 <p>Complexity is a cost, just like code size or runtime speed. Treat it as
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 365
diff changeset
189 a cost, and spend your complexity budget wisely. (Sometimes this means you
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 365
diff changeset
190 can't afford a feature because it complicates the code too much to be
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 365
diff changeset
191 worth it.)</p>
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
192
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
193 <p>Simplicity has lots of benefits. Simple code is easy to maintain, easy to
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
194 port to new processors, easy to audit for security holes, and easy to
1177
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
195 understand.</p>
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
196
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
197 <p>Simplicity itself can have subtle non-obvious aspects requiring a tradeoff
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
198 between one kind of simplicity and another: simple for the computer to
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
199 execute and simple for a human reader to understand aren't always the
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
200 same thing. A compact and clever algorithm that does very little work may
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
201 not be as easy to explain or understand as a larger more explicit version
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
202 requiring more code, memory, and CPU time. When balancing these, err on the
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
203 side of doing less work, but add comments describing how you
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
204 could be more explicit.</p>
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
205
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
206 <p>In general, comments are not a substitute for good code (or well chosen
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
207 variable or function names). Commenting "x += y;" with "/* add y to x */"
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
208 can actually detract from the program's readability. If you need to describe
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
209 what the code is doing (rather than _why_ it's doing it), that means the
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
210 code itself isn't very clear.</p>
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
211
529
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
212 <p>Prioritizing simplicity tends to serve our other goals: simplifying code
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
213 generally reduces its size (both in terms of binary size and runtime memory
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
214 usage), and avoiding unnecessary work makes code run faster. Smaller code
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
215 also tends to run faster on modern hardware due to CPU cacheing: fitting your
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
216 code into L1 cache is great, and staying in L2 cache is still pretty good.</p>
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
217
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
218 <p><a href=http://www.joelonsoftware.com/articles/fog0000000069.html>Joel
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
219 Spolsky argues against throwing code out and starting over</a>, and he has
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
220 good points: an existing debugged codebase contains a huge amount of baked
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
221 in knowledge about strange real-world use cases that the designers didn't
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
222 know about until users hit the bugs, and most of this knowledge is never
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
223 explicitly stated anywhere except in the source code.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
224
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
225 <p>That said, the Mythical Man-Month's "build one to throw away" advice points
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
226 out that until you've solved the problem you don't properly understand it, and
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
227 about the time you finish your first version is when you've finally figured
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
228 out what you _should_ have done. (The corrolary is that if you build one
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
229 expecting to throw it away, you'll actually wind up throwing away two. You
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
230 don't understand the problem until you _have_ solved it.)</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
231
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
232 <p>Joel is talking about what closed source software can afford to do: Code
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
233 that works and has been paid for is a corporate asset not lightly abandoned.
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
234 Open source software can afford to re-implement code that works, over and
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
235 over from scratch, for incremental gains. Before toybox, the unix command line
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents: 156
diff changeset
236 has already been reimplemented from scratch several times in a row (the
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents: 156
diff changeset
237 original AT&amp;T Unix command line in assembly and then in C, the BSD
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents: 156
diff changeset
238 versions, the GNU tools, BusyBox...) but maybe toybox can do a better job. :)</p>
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
239
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
240 <p>P.S. How could I resist linking to an article about
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
241 <a href=http://blog.outer-court.com/archive/2005-08-24-n14.html>why
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
242 programmers should strive to be lazy and dumb</a>?</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
243
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
244 <b><h2>Portability issues</h2></b>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
245
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
246 <b><h3>Platforms</h3></b>
1177
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
247 <p>Toybox should run on Android (all commands with musl-libc, as large a subset
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
248 as practical with bionic), and every other hardware platform Linux runs on.
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
249 Other posix/susv4 environments (perhaps MacOS X or newlib+libgloss) are vaguely
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
250 interesting but only if they're easy to support; I'm not going to spend much
6083bc6005a2 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.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
251 effort on them.</p>
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
252
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
253 <p>I don't do windows.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
254
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
255 <b><h3>32/64 bit</h3></b>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
256 <p>Toybox should work on both 32 bit and 64 bit systems. By the end of 2008
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
257 64 bit hardware will be the new desktop standard, but 32 bit hardware will
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
258 continue to be important in embedded devices for years to come.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
259
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
260 <p>Toybox relies on the fact that on any Unix-like platform, pointer and long
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
261 are always the same size (on both 32 and 64 bit). Pointer and int are _not_
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
262 the same size on 64 bit systems, but pointer and long are.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
263
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
264 <p>This is guaranteed by the LP64 memory model, a Unix standard (which Linux
114
ce6956dfc0cf Add sync and an incomplete version of mdev.
Rob Landley <rob@landley.net>
parents: 24
diff changeset
265 and MacOS X both implement). See
24
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
266 <a href=http://www.unix.org/whitepapers/64bit.html>the LP64 standard</a> and
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
267 <a href=http://www.unix.org/version2/whatsnew/lp64_wp.html>the LP64
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
268 rationale</a> for details.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
269
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
270 <p>Note that Windows doesn't work like this, and I don't care.
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
271 <a href=http://blogs.msdn.com/oldnewthing/archive/2005/01/31/363790.aspx>The
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
272 insane legacy reasons why this is broken on Windows are explained here.</a></p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
273
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
274 <b><h3>Signedness of char</h3></b>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
275 <p>On platforms like x86, variables of type char default to unsigned. On
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
276 platforms like arm, char defaults to signed. This difference can lead to
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
277 subtle portability bugs, and to avoid them we specify which one we want by
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
278 feeding the compiler -funsigned-char.</p>
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
279
c8d0f1876c40 Web site updates, and a design document.
Rob Landley <rob@landley.net>
parents:
diff changeset
280 <p>The reason to pick "unsigned" is that way we're 8-bit clean by default.</p>
365
8f0b24cc7cd7 Minor web page updates (put header/footer back, add a few <hr> tags).
Rob Landley <rob@landley.net>
parents: 200
diff changeset
281
616
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
282 <p><h3>Error messages and internationalization:</h3></p>
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
283 <p>Error messages are extremely terse not just to save bytes, but because we
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
284 don't use any sort of _("string") translation infrastructure.</p>
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
285
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
286 <p>Thus "bad -A '%c'" is
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
287 preferable to "Unrecognized address base '%c'", because a non-english speaker
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
288 can see that -A was the problem, and with a ~20 word english vocabulary is
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
289 more likely to know (or guess) "bad" than the longer message.</p>
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
290
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
291 <p>The help text might someday have translated versions, and strerror()
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
292 messages produced by perror_exit() and friends can be expected to be
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
293 localized by libc. Our error functions also prepend the command name,
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
294 which non-english speakers can presumably recognize already.</p>
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
295
694
786841fdb1e0 Reindent to two spaces per level. Remove vi: directives that haven't worked right in years (ubuntu broke its' vim implementation). Remove trailing spaces. Add/remove blank lines. Re-wordwrap in places. Update documentation with new coding style.
Rob Landley <rob@landley.net>
parents: 616
diff changeset
296 <p>An enventual goal is <a href=http://yarchive.net/comp/linux/utf8.html>UTF-8</a> support, although it isn't a priority for the
616
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
297 first pass of each command. (All commands should at least be 8-bit clean.)</p>
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
298
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
299 <p>Locale support isn't currently a goal; that's a presentation layer issue,
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
300 X11 or Dalvik's problem.</p>
e6acd7fbbfee A note on error messages and internationalization.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
301
1291
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
302 <a name="codestyle" />
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
303 <h2>Coding style</h2>
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
304
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
305 <p>The real coding style holy wars are over things that don't matter
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
306 (whitespace, indentation, curly bracket placement...) and thus have no
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
307 obviously correct answer. As in academia, "the fighting is so vicious because
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
308 the stakes are so small". That said, being consistent makes the code readable,
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
309 so here's how to make toybox code look like other toybox code.</p>
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
310
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
311 <p>Toybox source uses two spaces per indentation level, and wraps at 80
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
312 columns. (Indentation of continuation lines is awkward no matter what
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
313 you do, sometimes two spaces looks better, sometimes indenting to the
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
314 contents of a parentheses looks better.)</p>
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
315
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
316 <p>There's a space after C flow control statements that look like functions, so
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
317 "if (blah)" instead of "if(blah)". (Note that sizeof is actually an
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
318 operator, so we don't give it a space for the same reason ++ doesn't get
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
319 one. Yeah, it doesn't need the parentheses either, but it gets them.
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
320 These rules are mostly to make the code look consistent, and thus easier
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
321 to read.) We also put a space around assignment operators (on both sides),
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
322 so "int x = 0;".</p>
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
323
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
324 <p>Blank lines (vertical whitespace) go between thoughts. "We were doing that,
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
325 now we're doing this. (Not a hard and fast rule about _where_ it goes,
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
326 but there should be some.)"</p>
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
327
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
328 <p>Variable declarations go at the start of blocks, with a blank line between
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
329 them and other code. Yes, c99 allows you to put them anywhere, but they're
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
330 harder to find if you do that. If there's a large enough distance between
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
331 the declaration and the code using it to make you uncomfortable, maybe the
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
332 function's too big, or is there an if statement or something you can
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
333 use as an excuse to start a new closer block?</p>
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
334
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
335 <p>If statments with a single line body go on the same line if the result
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
336 fits in 80 columns, on a second line if it doesn't. We usually only use
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
337 curly brackets if we need to, either because the body is multiple lines or
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
338 because we need to distinguish which if an else binds to. Curly brackets go
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
339 on the same line as the test/loop statement. The exception to both cases is
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
340 if the test part of an if statement is long enough to split into multiple
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
341 lines, then we put the curly bracket on its own line afterwards (so it doesn't
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
342 get lost in the multple line variably indented mess), and we put it there
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
343 even if it's only grouping one line (because the indentation level is not
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
344 providing clear information in that case).</p>
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
345
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
346 <p>I.E.</p>
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
347
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
348 <blockquote>
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
349 <pre>
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
350 if (thingy) thingy;
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
351 else thingy;
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
352
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
353 if (thingy) {
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
354 thingy;
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
355 thingy;
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
356 } else thingy;
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
357
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
358 if (blah blah blah...
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
359 && blah blah blah)
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
360 {
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
361 thingy;
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
362 }
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
363 </pre></blockquote>
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
364
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
365 <p>Gotos are allowed for error handling, and for breaking out of
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
366 nested loops. In general, a goto should only jump forward (not back), and
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
367 should either jump to the end of an outer loop, or to error handling code
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
368 at the end of the function. Goto labels are never indented: they override the
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
369 block structure of the file. Putting them at the left edge makes them easy
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
370 to spot as overrides to the normal flow of control, which they are.</p>
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
371
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
372 <p>When there's a shorter way to say something, we tend to do that for
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
373 consistency. For example, we tend to say "*blah" instead of "blah[0]" unless
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
374 we're referring to more than one element of blah. Similarly, NULL is
1336
97c7f42068b5 Minor tweaks to code style section.
Rob Landley <rob@landley.net>
parents: 1291
diff changeset
375 really just 0 (and C will automatically typecast 0 to anything, except in
97c7f42068b5 Minor tweaks to code style section.
Rob Landley <rob@landley.net>
parents: 1291
diff changeset
376 varargs), "if (function() != NULL)" is the same as "if (function())",
97c7f42068b5 Minor tweaks to code style section.
Rob Landley <rob@landley.net>
parents: 1291
diff changeset
377 "x = (blah == NULL);" is "x = !blah;", and so on.</p>
97c7f42068b5 Minor tweaks to code style section.
Rob Landley <rob@landley.net>
parents: 1291
diff changeset
378
97c7f42068b5 Minor tweaks to code style section.
Rob Landley <rob@landley.net>
parents: 1291
diff changeset
379 <p>The goal is to be
1291
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
380 concise, not cryptic: if you're worried about the code being hard to
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
381 understand, splitting it to multiple steps on multiple lines is
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
382 better than a NOP operation like "!= NULL". A common sign of trying to
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
383 hard is nesting ? : three levels deep, sometimes if/else and a temporary
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
384 variable is just plain easier to read. If you think you need a comment,
1336
97c7f42068b5 Minor tweaks to code style section.
Rob Landley <rob@landley.net>
parents: 1291
diff changeset
385 you may be right.</p>
1291
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
386
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
387 <p>Comments are nice, but don't overdo it. Comments should explain _why_,
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
388 not how. If the code doesn't make the how part obvious, that's a problem with
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
389 the code. Sometimes choosing a better variable name is more revealing than a
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
390 comment. Comments on their own line are better than comments on the end of
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
391 lines, and they usually have a blank line before them. Most of toybox's
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
392 comments are c99 style // single line comments, even when there's more than
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
393 one of them. The /* multiline */ style is used at the start for the metadata,
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
394 but not so much in the code itself. They don't nest cleanly, are easy to leave
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
395 accidentally unterminated, need extra nonfunctional * to look right, and if
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
396 you need _that_ much explanation maybe what you really need is a URL citation
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
397 linking to a standards document? Long comments can fall out of sync with what
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
398 the code is doing. Comments do not get regression tested. There's no such
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
399 thing as self-documenting code (if nothing else, code with _no_ comments
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
400 is a bit unfriendly to new readers), but "chocolate sauce isn't the answer
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
401 to bad cooking" either. Don't use comments as a crutch to explain unclear
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
402 code if the code can be fixed.</p>
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html.
Rob Landley <rob@landley.net>
parents: 1180
diff changeset
403
365
8f0b24cc7cd7 Minor web page updates (put header/footer back, add a few <hr> tags).
Rob Landley <rob@landley.net>
parents: 200
diff changeset
404 <!--#include file="footer.html" -->