Technology As If People MatteredRuss Olsen's tech bloghttp://russolsen.com/articles2018-04-24T20:00:00-04:00Russ OlsenSome Important Numbers For Developershttp://russolsen.com/articles/2018/04/25/some-important-numbers-for-developers.html2018-04-24T20:00:00-04:002018-04-22T13:44:04-04:00Article Author<blockquote>
<p>This is another really old article, but one that is still close to my heart.</p>
</blockquote>
<p>Software engineering is one of those semi-mathematical technical professions that is just chock full of numbers. Our machines run at so many gigahertz and produce some exact number of mega-flops. We have deal in the hard physical reality of memory in kilobytes and the more ethereal idea of so many big O's for each sub N. But I've been thinking that there are some numbers that we have been neglecting. For example:</p>
<h2 id="three">THREE</h2>
<p>The optimum number of software engineers that can collaborate on a single project. As Fred Brooks pointed out long ago, people are simultaneously the power source and one of the main impediments to writing code. Add some more people to your project and they might make things spin faster, but more people can also slow progress down, since more people means more meetings, more memos and more misunderstandings. I know that there are lots of projects out there that require more than three people, but I do think that three is an optimal point on the curve.</p>
<!-- more -->
<h2 id="zero">ZERO</h2>
<p>The number of uniquely correct solutions to any given software problem. The key word here is 'uniquely': Just about all real word problems have many fine solutions, not just one. The belief that my solution is the one true way is almost certainly wrong and is quite likely to drive down another important figure: the number of working solutions that we actually manage to produce.</p>
<h2 id="infinity">INFINITY</h2>
<p>The number of incorrect solutions to any given software problem. Just because I think that are many good solutions doesn't mean that yours happens to be one of them.</p>
<h2 id="section">500,000</h2>
<p>An estimate of the number of ways that any given programming problem might be solved, at least within the borders of the United States. As it happens, there are also about half a million coders working in the US at the moment. This estimate might be high, since not every coder will have an opinion on every problem. On the other hand it might be low: I tend to change my mind six times before lunch. On a good day.</p>
<h2 id="section-1">625</h2>
<p>Six hundred and twenty five is approximately the number of programming languages found on wikipedia list of programming languages. Lately I have been playing with Erlang which is a functional programming language designed for concurrency. It is such a weird language that I've nearly given up three or four times, but I have each time I come back to it with that – Oh, I see! – feeling. At this point the jury in my head (it's amazing we can all fit in there) is still out, but I am sure of one thing: learning about Erlang has changed the way that I think about programs and computing, changed it in some subtle ways.</p>
<p>But Erlang is just one of 625 and each of those languages represents a unique view of the computing terrain as well as a vehicle for crossing that terrain. Most of those 625 languages are destined to live out their lives in well deserved obscurity, but taken as a group they sum up much of the thinking that we have done in the past half century on how to build programs. Have you learned a new language lately?</p>
<h2 id="three-1">THREE</h2>
<p>The number of programmers who will write most of the code in a system developed by a team of 24 engineers, two project managers, three group leaders, a quality lead and an office manager.</p>
<p>– Russ</p>
Write English the Way You Write Codehttp://russolsen.com/articles/2018/04/21/write-english.html2018-04-20T20:00:00-04:002018-04-22T13:45:34-04:00Article Author<blockquote>
<p>Another very early article, from 2006, but very much in the spirit of the explaining series. – Russ</p>
</blockquote>
<p>Some years ago I was managing a software group that was doing joint development with a team in Japan. My company spent a lot of money to translate a design document from Japanese into English. The result was indecipherable gobbledygook. When I complained about the quality of the translation to the Japanese manager, he just shook his head. No, he said, it wasn't the translator: the document was just as unreadable in the native Japanese. And nobody was surprised.</p>
<p>For a profession full of sharp people, software engineering produces some hideous prose. How many times have you tried to read a technical document and failed because it was, in a very real sense, unreadable? It doesn't have to be this way. We technical types can improve our writing simply by applying some of those hard won coding skills to to those other, human, languages. I may be grammar challenged and spelling incapable, but writing code has taught me a few things about writing for people.</p>
<h2 id="do-one-thing-well">Do one thing well</h2>
<p>If we have learned anything about building programs in the last few decades, it is that each method, class, module or program should do one thing, and do it well. When a GUI tries to be both pretty and the center of the business logic, you are headed for disaster. Write database code that also tries to handle the network traffic and you are just setting yourself up for a fall. No, a program needs to concentrate on one thing, and do the best it can at that one thing.</p>
<p>So does your writing. If you are writing installation instructions, tell me how to install the thing. I don't want the theory of how it works. I don't want to know how it was was designed. I don't want to know why you picked Linux over Mac. I just want to know how to install it. I don't think that people deliberately wander off the point, but a lot of technical people are just dying to tell the world what a great job they have done, why they picked this over that, how hard it all was. Great: write a status report, or a blog, or the Great American Technical Memoir. The practice will do you good. But as for the installation instructions, just tell me how to install it. Then write the best code…er…English that you can come up with to make that happen.</p>
<h2 id="test-test-and-then-test-again">Test, test and then test again</h2>
<p>The oldest joke in software engineering is probably the one where the engineer says, <em>Well it compiles, so it must be right.</em> Everyone in the software business knows that getting a program to compile is just the first, and usually the easiest step to getting it to work. If you want to know if some code works, you need to run it. If you want to know if your prose works, read it. Out loud. There is something about running your words out of your mouth and back into you ears that is the text equivalent of unit testing. If you find you are gasping for breath, perhaps your sentences are too long. If reading your stuff makes you feel like you are trying to say <em>She sells sea shells at the sea shore</em>, maybe you should consider rewording. Reading your stuff out loud will also help you spot those places where you annoyingly use the same annoying word in annoying profusion.</p>
<p>I guess that if reading your own work out loud is unit testing, then having someone else read it is beta testing. If part of your job is writing, then a kind but honest reviewer is worth more than a fancy word processor and two dictionaries. And what's the best way to get someone to review your stuff? By reviewing theirs, of course.</p>
<h2 id="dont-repeat-yourself-much">Don't repeat yourself (much)</h2>
<p>DRY is about as close to a commandment as we have in the programming world. Keeping redundant code to a minimum means that your code is easier to understand, it means that bugs can be found and fixed once, and it means that you simply have less code to deal with. Generally it is much the same when you are writing for people. You want to avoid repeating large blocks of text or the same explanations over and over. If you are writing the design document, don't repeat the requirements; point the reader back to requirements document. Avoid redundancy in your prose for exactly the same reasons you avoid it in code: your document will not only be smaller, but it will seem more organized. If you make a mistake, there is only one place to fix.</p>
<p>Don't take this advice too far, however. People are, well, human, and they do tend to forget. It is not bad to remind your reader every now and then of the some critical fact: <em>remember, as we explained in chapter one, don't let the blue wire touch the detonator</em>. Sometimes you can spot the places where a little repetition will do some good by taking a break and rereading your document later. Things that seemed obvious when you were writing will sometimes become completely obscure an hour later.</p>
<p>Keep in mind that there is no harm in providing some context, but you have to strike a balance between helpful reminders and the deadly retelling of section 1.4.7.c, subparagraph 4.</p>
<h2 id="dont-write-to-impress-me">Don't write to impress me</h2>
<p>There are lots of ways to write programs, some good and some bad, but perhaps the worst way is to write code to impress the reader. You see this in programs that refuse to do a simple thing simply. Need to find an particular item in a list of ten? Well let's pull out that highly optimized binary search algorithm. Need to build one dialog? Let's write a special GUI framework to support it. Want to add two plus two? Then clearly you will need a factory which produces the command which grabs the facade for the bridge to your <code>NumberAddition</code> class. I think we have all seen too much code that is written mainly to demonstrate the cleverness of the author.</p>
<p>So why is it that engineers who would never think of coding to impress, write documents that are full of impressive sounding words? We don't have a thing, we have an <em>Artifact</em>. We don't pull it all together, we <em>Create an Aggregation</em>. We don't work together, we <em>Collaborate</em>. And come up with <em>Canonical</em> answers. And don't forget the worst offender, <em>facilitate</em>.
Even worse, we string them together: <em>Hey kids, let's aggregate the artifactS to facilitate canonical collaborations!</em></p>
<p>Don't get me wrong – these are all perfectly good words. The problem with these words, and all of their polysyllabic friends, is that they are like the complex algorithm or the fancy framework. Frameworks and fancy words have their place, but if you are only pulling them out to impress me, it ain't gonna work. Overuse the fancy words and you make yourself sound like you are dumb and trying to pretend that you are smart.</p>
<p>Here's a little secret: getting your point across in as few, short words as possible shows that you care about the reader. It shows that you know your goal is to communicate. It shows that you are just trying to get it done. In short, it shows that you are smart. I can't really do better than to repeat George Orwell, who, seventy years ago, asked if you would rather read this:</p>
<blockquote>
<p>Objective considerations of contemporary phenomena compel the conclusion that success or failure in competitive activities exhibits no tendency to be commensurate with innate capacity, but that a considerable element of the unpredictable must invariably be taken into account.</p>
</blockquote>
<p>Or this:</p>
<blockquote>
<p>I returned and saw under the sun, that the race is not to the swift, nor the battle to the strong, neither yet bread to the wise, nor yet riches to men of understanding, nor yet favour to men of skill; but time and chance happeneth to them all.</p>
</blockquote>
<p>So how do you do it? How to you stick to small, pointy words that work? Start by trying to write like you talk. Very few people walk around saying things like <em>Objective considerations of contemporary phenomena…</em> If you say it out loud, most of the pretentious words will simply fall away. Remember, the race may not always go to the swift, but the readers' thanks will always go to the concise.</p>
<h3 id="wrapping-up">Wrapping Up</h3>
<p>So there it is: know why you are writing and try to get it done. Read it out loud early and often. Don't repeat yourself unless it really helps the cause. And don't try to impress me. If you think about it, writing is the art of programming that wet computer that sits between your reader's ears. When you start, ask yourself how you are trying to change the state of your reader's mind. With that goal firmly in sight, write the best code you can.</p>
<p>– Russ</p>
Functionial Dreams (Part 2)http://russolsen.com/articles/2018/04/16/fun-dreams2.html2018-04-15T20:00:00-04:002018-04-22T13:38:14-04:00Article Author
<p><a href="/articles/2018/04/15/fun-dreams.html">sometimes i dream in code</a></p>
<p>bits of programs <br />
glide around <br />
in my head</p>
<p>sometimes i dream <br />
that my data structures are all immutable
and that I've made
little one method, no data
object</p>
<p>objects i call functions</p>
<p>sometimes i dream
that these function things <br />
are already there</p>
<pre class="highlight ruby"><code>
<span class="n">make_description</span> <span class="o">=</span> <span class="nb">lambda</span> <span class="p">{</span><span class="o">|</span><span class="n">b</span><span class="o">|</span> <span class="s2">"</span><span class="si">#{</span><span class="vi">@title</span><span class="si">}</span><span class="s2"> by </span><span class="si">#{</span><span class="vi">@author</span><span class="si">}</span><span class="s2"> / </span><span class="si">#{</span><span class="vi">@year_publ</span><span class="si">}</span><span class="s2">"</span><span class="p">}</span>
</code></pre>
<p>and i don't have to do anything <br />
then it's a good dream</p>
<pre class="highlight javascript"><code>
<span class="kd">function</span> <span class="nx">pipeline</span><span class="p">(</span><span class="nx">value</span><span class="p">,</span> <span class="nx">funcs</span><span class="p">)</span> <span class="p">{</span>
<span class="k">for</span><span class="p">(</span><span class="nx">i</span> <span class="k">in</span> <span class="nx">funcs</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">value</span> <span class="o">=</span> <span class="nx">funcs</span><span class="p">[</span><span class="nx">i</span><span class="p">](</span><span class="nx">value</span><span class="p">);</span>
<span class="p">}</span>
<span class="k">return</span> <span class="nx">value</span><span class="p">;</span>
<span class="p">}</span>
<span class="kd">function</span> <span class="nx">compose</span><span class="p">(</span><span class="nx">funcs</span><span class="p">){</span>
<span class="k">return</span> <span class="kd">function</span><span class="p">(</span><span class="nx">value</span><span class="p">){</span>
<span class="k">return</span> <span class="nx">pipeline</span><span class="p">(</span><span class="nx">value</span><span class="p">,</span> <span class="nx">funcs</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">}</span>
</code></pre>
<p>now <br />
my functions are things <br />
i can start with an array <br />
of function things <br />
and turn them into a new function</p>
<pre class="highlight ruby"><code>
<span class="k">def</span> <span class="nf">upper</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
<span class="n">s</span><span class="p">.</span><span class="nf">upcase</span>
<span class="k">end</span>
<span class="k">def</span> <span class="nf">title</span><span class="p">(</span><span class="n">book</span><span class="p">)</span>
<span class="c1">#puts "title for book #{book}"</span>
<span class="n">book</span><span class="p">[</span><span class="ss">:title</span><span class="p">]</span>
<span class="k">end</span>
<span class="n">upperCaseTitle</span><span class="o">=</span><span class="n">compose</span><span class="p">([</span><span class="nb">method</span><span class="p">(</span><span class="ss">:title</span><span class="p">),</span> <span class="nb">method</span><span class="p">(</span><span class="ss">:upper</span><span class="p">)])</span>
<span class="n">big_title</span> <span class="o">=</span> <span class="n">upperCaseTitle</span><span class="p">.</span><span class="nf">call</span><span class="p">(</span><span class="n">pride</span><span class="p">)</span>
</code></pre>
<p>i can assemble <br />
functions <br />
like legos</p>
<pre class="highlight python"><code>
<span class="n">new_array</span> <span class="o">=</span> <span class="p">[]</span>
<span class="k">for</span> <span class="n">b</span> <span class="ow">in</span> <span class="n">books</span><span class="p">:</span>
<span class="n">new_array</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">big_title</span><span class="p">(</span><span class="n">b</span><span class="p">))</span>
</code></pre>
<p>sometimes i want to <br />
loop over an array <br />
doing something <br />
to each element</p>
<p>but <br />
loops are hard</p>
<p>there's <br />
loop variables <br />
and making a new array <br />
for the result</p>
<p>and <br />
my code is all wrapped up <br />
in these function things</p>
<pre class="highlight python"><code>
<span class="k">def</span> <span class="nf">nap_map</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="n">arry</span><span class="p">):</span>
<span class="n">result</span> <span class="o">=</span> <span class="p">[]</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">arry</span><span class="p">)):</span>
<span class="n">result</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="n">arry</span><span class="p">[</span><span class="n">i</span><span class="p">]))</span>
<span class="k">return</span> <span class="n">result</span>
<span class="n">new_array</span> <span class="o">=</span> <span class="n">nap_map</span><span class="p">(</span><span class="n">upperCaseTitle</span><span class="p">,</span> <span class="n">books</span><span class="p">)</span>
</code></pre>
<p>so i write a function <br />
that does the loop for me</p>
<pre class="highlight javascript"><code>
<span class="kd">var</span> <span class="nx">new_array</span> <span class="o">=</span> <span class="nx">books</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">upperCaseTitle</span><span class="p">);</span>
</code></pre>
<p>sometimes in my dream <br />
this function is <br />
already there</p>
<p>and i roll over <br />
and make yummy noises</p>
<pre class="highlight plaintext"><code>
C ITS HARD TO SLEEP WHEN YOUR CODE IS SHOUTING
C BUT FORTRAN IV HAS NO LOWERCASE
C NO INSIDE VOICE
</code></pre>
<p>sometimes i want <br />
to combine <br />
the elements of an array <br />
together <br />
into a single value</p>
<pre class="highlight ruby"><code>
<span class="n">a</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">]</span>
<span class="n">result</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">a</span><span class="p">.</span><span class="nf">each</span> <span class="p">{</span><span class="o">|</span><span class="n">x</span><span class="o">|</span> <span class="n">result</span> <span class="o">=</span> <span class="n">result</span> <span class="o">+</span> <span class="n">x</span><span class="p">}</span>
</code></pre>
<p>like when i want to <br />
add all the numbers <br />
in an array <br />
together</p>
<p>but loops are a lot of work <br />
i’m too tired <br />
to repeat <br />
all that work</p>
<p>so i write a function <br />
that reduces the work</p>
<pre class="highlight ruby"><code>
<span class="k">def</span> <span class="nf">resting_reduce</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="n">arry</span><span class="p">)</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">arry</span><span class="p">.</span><span class="nf">first</span>
<span class="n">arry</span><span class="p">.</span><span class="nf">shift</span><span class="p">.</span><span class="nf">each</span> <span class="p">{</span><span class="o">|</span><span class="n">x</span><span class="o">|</span> <span class="n">result</span> <span class="o">=</span> <span class="n">f</span><span class="p">(</span><span class="n">result</span><span class="p">,</span> <span class="n">x</span><span class="p">)}</span>
<span class="n">result</span>
<span class="k">end</span>
</code></pre>
<p>all i <br />
supply is the function <br />
to combine <br />
an element with <br />
the current result</p>
<pre class="highlight ruby"><code>
<span class="n">numbers</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">]</span>
<span class="n">sum</span> <span class="o">=</span> <span class="n">resting_reduce</span><span class="p">(</span><span class="nb">method</span><span class="p">(</span><span class="ss">:add2</span><span class="p">),</span> <span class="mi">0</span><span class="p">,</span> <span class="n">numbers</span><span class="p">)</span>
</code></pre>
<p>that’s kind of hard <br />
so i pull <br />
the covers over my head <br />
but easier <br />
than the loop thing</p>
<pre class="highlight java"><code>
<span class="cm">/* Java coding standard - method parameters
* The number of parameters that required by a method
* should be proportional to the good that the method does
* 0-4: Ordinary application methods
* 5-6: System accounting and free pretzels
* 7-9: Methods generating world peas
* 10+: No excuse
*/</span>
</code></pre>
<p>sometimes i have <br />
a function <br />
lots of arguments <br />
i already know the values <br />
of the first few arguments <br />
writing out all those arguments <br />
over and over</p>
<p>is hard</p>
<pre class="highlight python"><code>
<span class="k">def</span> <span class="nf">placid_partial</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">):</span>
<span class="k">return</span> <span class="k">lambda</span> <span class="o">*</span><span class="n">more_args</span><span class="p">:</span> <span class="n">f</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">*</span><span class="n">more_args</span><span class="p">)</span>
</code></pre>
<p>so i write a function <br />
that gives me a function <br />
that does the same thing</p>
<pre class="highlight javascript"><code>
<span class="kd">function</span> <span class="nx">add2</span><span class="p">(</span><span class="nx">a</span><span class="p">,</span> <span class="nx">b</span><span class="p">)</span> <span class="p">{</span><span class="k">return</span> <span class="nx">a</span> <span class="o">+</span> <span class="nx">b</span><span class="p">}</span>
<span class="kd">var</span> <span class="nx">increment</span> <span class="o">=</span> <span class="nx">placid_partial</span><span class="p">(</span><span class="nx">add2</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span>
</code></pre>
<p>but fills in the arguments</p>
<p>it's a pain <br />
but less pain <br />
than writing this stuff <br />
over and over</p>
<pre class="highlight javascript"><code>
<span class="kd">var</span> <span class="nx">pride</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Pride and Prejudice"</span><span class="p">,</span> <span class="s2">"author"</span><span class="p">:</span> <span class="s2">"Austen"</span><span class="p">,</span> <span class="s2">"published"</span><span class="p">:</span> <span class="mi">1813</span><span class="p">};</span>
</code></pre>
<p>sometimes <br />
i'm tired of typing <br />
semicolons <br />
and commas <br />
and all the rest</p>
<p>in my dream <br />
i make them <br />
go away</p>
<pre class="highlight javascript"><code>
<span class="nx">pride</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"title"</span> <span class="s2">"Pride and Prejudice"</span> <span class="s2">"author"</span> <span class="s2">"Austen"</span> <span class="s2">"published"</span> <span class="mi">1813</span><span class="p">}</span>
</code></pre>
<p>better</p>
<p>but there are still <br />
a lot of rules <br />
a lot</p>
<pre class="highlight javascript"><code>
<span class="kd">function</span> <span class="nx">nap_map</span><span class="p">(</span><span class="nx">f</span><span class="p">,</span> <span class="nx">arry</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">result</span> <span class="o">=</span> <span class="p">[];</span>
<span class="k">for</span><span class="p">(</span><span class="nx">i</span> <span class="k">in</span> <span class="nx">arry</span><span class="p">){</span>
<span class="nx">result</span><span class="p">.</span><span class="nx">push</span><span class="p">(</span><span class="nx">f</span><span class="p">(</span><span class="nx">arry</span><span class="p">[</span><span class="nx">i</span><span class="p">]));</span>
<span class="p">}</span>
<span class="k">return</span> <span class="nx">result</span><span class="p">;</span>
<span class="p">}</span>
</code></pre>
<p>do i have parentheses <br />
do i have braces? <br />
is END a thing?</p>
<p>too hard</p>
<pre class="highlight plaintext"><code>
function(nap_map [f arry]
set(result [])
for(i in arry
push(result f(get(arry i)))
)
return(result))
</code></pre>
<p>make everything <br />
look like <br />
a function call</p>
<p>now there is less to remember <br />
i can end <br />
this exhausting REM sleep <br />
and go back <br />
to being truly unconscious</p>
<pre class="highlight plaintext"><code>
[1 2 3 4]
</code></pre><p>sometimes i’m making an array</p>
<pre class="highlight plaintext"><code>
add2(1 3)
</code></pre>
<p>sometimes i’m calling a function</p>
<p>sometimes i forget <br />
to put the name of the function <br />
on the outside</p>
<pre class="highlight plaintext"><code>
(add2 1 3)
</code></pre>
<p>in my dream i <br />
stick the name of the function <br />
on the inside <br />
like an array</p>
<pre class="highlight clojure"><code><span class="w">
</span><span class="p">(</span><span class="nf">function</span><span class="w"> </span><span class="n">upper</span><span class="w"> </span><span class="p">[</span><span class="n">s</span><span class="p">]</span><span class="w"> </span><span class="p">(</span><span class="nf">return</span><span class="w"> </span><span class="p">(</span><span class="nf">toUpperCase</span><span class="w"> </span><span class="n">s</span><span class="p">)))</span><span class="w">
</span><span class="p">(</span><span class="nf">function</span><span class="w"> </span><span class="n">title</span><span class="w"> </span><span class="p">[</span><span class="n">book</span><span class="p">]</span><span class="w"> </span><span class="p">(</span><span class="nf">return</span><span class="w"> </span><span class="p">(</span><span class="nf">title</span><span class="w"> </span><span class="n">book</span><span class="p">)))</span><span class="w">
</span><span class="p">(</span><span class="k">def</span><span class="w"> </span><span class="n">upperCaseTile</span><span class="w"> </span><span class="p">(</span><span class="nf">compose</span><span class="w"> </span><span class="p">[</span><span class="n">title,</span><span class="w"> </span><span class="n">upper</span><span class="p">]))</span><span class="w">
</span><span class="p">(</span><span class="k">def</span><span class="w"> </span><span class="n">bigTitle</span><span class="w"> </span><span class="p">(</span><span class="nf">upperCaseTitle</span><span class="w"> </span><span class="n">pride</span><span class="p">))</span><span class="w">
</span></code></pre>
<p>and now there's <br />
two kinds of collections <br />
the ones with <br />
parentheses <br />
do something <br />
like call a function</p>
<p>the ones with square brackets <br />
are data</p>
<pre class="highlight shell"><code>
<span class="nb">time </span>my-program.jsrbpyjavaftnco
real 0m0.018s
user 0m0.001s
sys 0m0.006s
</code></pre>
<p>and in the predawn hours <br />
just before i wake up <br />
i dreamed <br />
that i <br />
waved my hands</p>
<p>and it all runs <br />
fast <br />
very fast</p>
<pre class="highlight clojure"><code><span class="w">
</span><span class="p">(</span><span class="k">def</span><span class="w"> </span><span class="n">pride</span><span class="w"> </span><span class="p">{</span><span class="no">:title</span><span class="w"> </span><span class="s">"Pride and Prejudice"</span><span class="w"> </span><span class="no">:author</span><span class="w"> </span><span class="s">"Austen"</span><span class="w"> </span><span class="no">:published</span><span class="w"> </span><span class="mi">1813</span><span class="p">})</span><span class="w">
</span><span class="p">(</span><span class="k">def</span><span class="w"> </span><span class="n">war</span><span class="w"> </span><span class="p">{</span><span class="no">:title</span><span class="w"> </span><span class="s">"War and Peace"</span><span class="w"> </span><span class="no">:author</span><span class="w"> </span><span class="s">"Tolstoy"</span><span class="w"> </span><span class="no">:published</span><span class="w"> </span><span class="mi">1869</span><span class="p">})</span><span class="w">
</span><span class="p">(</span><span class="k">def</span><span class="w"> </span><span class="n">zombies</span><span class="w"> </span><span class="p">{</span><span class="no">:title</span><span class="w"> </span><span class="s">"Pride and Prejudice and Zombies"</span><span class="w"> </span><span class="no">:author</span><span class="w"> </span><span class="s">"Grahame-Smith"</span><span class="w"> </span><span class="no">:published</span><span class="w"> </span><span class="mi">2009</span><span class="p">})</span><span class="w">
</span><span class="p">(</span><span class="k">def</span><span class="w"> </span><span class="n">books</span><span class="w"> </span><span class="p">[</span><span class="n">pride</span><span class="w"> </span><span class="n">war</span><span class="p">])</span><span class="w">
</span></code></pre>
<p>and as reality <br />
folds into my dream <br />
and i think now</p>
<pre class="highlight clojure"><code><span class="w">
</span><span class="p">(</span><span class="k">def</span><span class="w"> </span><span class="n">other-books</span><span class="w"> </span><span class="p">(</span><span class="nb">assoc</span><span class="w"> </span><span class="n">books</span><span class="w"> </span><span class="mi">0</span><span class="w"> </span><span class="n">zombies</span><span class="p">))</span><span class="w">
</span></code></pre>
<p>i can look away <br />
from my data <br />
without worrying <br />
that someone will <br />
mess with it</p>
<pre class="highlight clojure"><code><span class="w">
</span><span class="p">(</span><span class="k">defn</span><span class="w"> </span><span class="n">description</span><span class="w"> </span><span class="p">[</span><span class="n">b</span><span class="p">]</span><span class="w">
</span><span class="p">(</span><span class="nb">str</span><span class="w"> </span><span class="p">(</span><span class="no">:title</span><span class="w"> </span><span class="n">b</span><span class="p">)</span><span class="w"> </span><span class="s">" by "</span><span class="w"> </span><span class="p">(</span><span class="no">:author</span><span class="w"> </span><span class="n">b</span><span class="p">)</span><span class="w"> </span><span class="s">" published in "</span><span class="w"> </span><span class="p">(</span><span class="no">:published</span><span class="w"> </span><span class="n">b</span><span class="p">)))</span><span class="w">
</span></code></pre>
<p>i can write code <br />
without <br />
so much <br />
syntax</p>
<pre class="highlight clojure"><code><span class="w">
</span><span class="p">(</span><span class="k">defn</span><span class="w"> </span><span class="n">upper</span><span class="w"> </span><span class="p">[</span><span class="n">s</span><span class="p">]</span><span class="w"> </span><span class="p">(</span><span class="nf">.toUpperCase</span><span class="w"> </span><span class="n">s</span><span class="p">))</span><span class="w">
</span></code></pre>
<p>my code lives <br />
in tidy little function <br />
which are things</p>
<p>my functions operate</p>
<pre class="highlight clojure"><code><span class="w">
</span><span class="p">(</span><span class="k">def</span><span class="w"> </span><span class="n">yelling-title</span><span class="w"> </span><span class="p">(</span><span class="nf">upper</span><span class="w"> </span><span class="s">"War and Peace"</span><span class="p">))</span><span class="w">
</span></code></pre>
<p>on simple values</p>
<pre class="highlight clojure"><code><span class="w">
</span><span class="p">(</span><span class="k">def</span><span class="w"> </span><span class="n">yelling-titles</span><span class="w"> </span><span class="p">(</span><span class="nb">map</span><span class="w"> </span><span class="n">upper</span><span class="w"> </span><span class="p">[</span><span class="s">"Emma"</span><span class="w"> </span><span class="s">"Jaws"</span><span class="w"> </span><span class="s">"The Giver"</span><span class="p">]))</span><span class="w">
</span></code></pre>
<p>on collections</p>
<pre class="highlight clojure"><code><span class="w">
</span><span class="p">(</span><span class="k">def</span><span class="w"> </span><span class="n">extract-yelling-title</span><span class="w"> </span><span class="p">(</span><span class="nb">comp</span><span class="w"> </span><span class="n">upper</span><span class="w"> </span><span class="no">:title</span><span class="p">))</span><span class="w">
</span></code></pre>
<p>on each other</p>
<p>it all runs fast</p>
<p>in my dream <br />
the living is good <br />
the programming is easy</p>
<p><a href="https://pragprog.com/book/roclojure/getting-clojure">live the dream</a> <br />
<a href="https://pragprog.com/book/roclojure/getting-clojure">clojure</a></p>
<p>– Russ</p>
<blockquote>
<p><em>A version of this article originally appeared on <a href="http://cognitect.com">Cognitect blog</a>.</em></p>
</blockquote>
Functionial Dreams (Part 1)http://russolsen.com/articles/2018/04/15/fun-dreams.html2018-04-14T20:00:00-04:002018-04-22T13:38:59-04:00Article Author
<p>sometimes<br />
i dream in code</p>
<pre class="highlight python"><code>
<span class="k">class</span> <span class="nc">Book</span><span class="p">:</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">a</span><span class="p">,</span> <span class="n">t</span><span class="p">,</span> <span class="n">p</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">author</span> <span class="o">=</span> <span class="n">a</span>
<span class="bp">self</span><span class="o">.</span><span class="n">title</span> <span class="o">=</span> <span class="n">t</span>
<span class="bp">self</span><span class="o">.</span><span class="n">published</span> <span class="o">=</span> <span class="n">p</span>
<span class="k">def</span> <span class="nf">description</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">title</span> <span class="o">+</span> <span class="s">" by "</span> <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">author</span> <span class="o">+</span> <span class="s">" published in "</span> <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">published</span>
</code></pre>
<p>bits of programs <br />
glide around <br />
in my head</p>
<pre class="highlight javascript"><code>
<span class="kd">function</span> <span class="nx">Book</span> <span class="p">(</span><span class="nx">t</span><span class="p">,</span> <span class="nx">a</span><span class="p">,</span> <span class="nx">p</span><span class="p">)</span> <span class="p">{</span>
<span class="k">this</span><span class="p">.</span><span class="nx">title</span> <span class="o">=</span> <span class="nx">t</span><span class="p">;</span>
<span class="k">this</span><span class="p">.</span><span class="nx">author</span> <span class="o">=</span> <span class="nx">a</span><span class="p">;</span>
<span class="k">this</span><span class="p">.</span><span class="nx">published</span> <span class="o">=</span> <span class="nx">p</span><span class="p">;</span>
<span class="k">this</span><span class="p">.</span><span class="nx">description</span> <span class="o">=</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="k">return</span> <span class="k">this</span><span class="p">.</span><span class="nx">title</span> <span class="o">+</span> <span class="s1">' by '</span> <span class="o">+</span> <span class="k">this</span><span class="p">.</span><span class="nx">author</span> <span class="o">+</span> <span class="s1">' published in '</span> <span class="o">+</span> <span class="k">this</span><span class="p">.</span><span class="nx">published</span><span class="p">;</span>
<span class="p">};</span>
<span class="k">return</span> <span class="k">this</span><span class="p">;</span>
<span class="p">}</span>
</code></pre>
<p>i close my eyes <br />
and there it is <br />
code</p>
<pre class="highlight plaintext"><code>
0900 Dim thisBook As book
</code></pre>
<p>always the code <br />
pointy k's <br />
and bumpy m's</p>
<p>it follows me <br />
from one rem cycle <br />
to the next</p>
<pre class="highlight plaintext"><code>
01 BOOK
05 TITLE PIC X(15).
05 AUTHOR PIC X(15).
05 YEARPUB PIC 9(4).
</code></pre>
<p>i've used <br />
a lot of <br />
programming languages</p>
<pre class="highlight java"><code>
<span class="kd">class</span> <span class="nc">Book</span> <span class="o">{</span>
<span class="kd">private</span> <span class="n">String</span> <span class="n">title</span><span class="o">;</span>
<span class="kd">private</span> <span class="n">String</span> <span class="n">author</span><span class="o">;</span>
<span class="kd">private</span> <span class="kt">int</span> <span class="n">year_published</span><span class="o">;</span>
<span class="kd">public</span> <span class="nf">Book</span><span class="o">(</span><span class="n">t</span><span class="o">,</span> <span class="n">a</span><span class="o">,</span> <span class="n">p</span><span class="o">)</span> <span class="o">{</span>
<span class="n">title</span> <span class="o">=</span> <span class="n">t</span><span class="o">;</span>
<span class="n">author</span> <span class="o">=</span> <span class="n">a</span><span class="o">;</span>
<span class="n">year_published</span> <span class="o">=</span> <span class="n">p</span><span class="o">;</span>
<span class="o">}</span>
<span class="kd">public</span> <span class="nf">getDescription</span><span class="o">()</span> <span class="o">{</span>
<span class="k">return</span> <span class="n">title</span> <span class="o">+</span> <span class="s">" by "</span> <span class="o">+</span> <span class="n">author</span> <span class="o">+</span> <span class="s">" published in "</span> <span class="o">+</span> <span class="n">year_published</span><span class="o">;</span>
<span class="o">}</span>
<span class="o">}</span>
</code></pre>
<p>from BASIC to FORTRAN</p>
<pre class="highlight plaintext"><code>
0100 author = "Tolstoy"
0200 title = "War and Peace"
0300 published = 1869
</code></pre>
<p>to Ruby and Python</p>
<pre class="highlight ruby"><code>
<span class="k">class</span> <span class="nc">Book</span>
<span class="kp">attr_accessor</span> <span class="ss">:author</span><span class="p">,</span> <span class="ss">:title</span><span class="p">,</span> <span class="ss">:published</span>
<span class="k">def</span> <span class="nf">initialize</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">t</span><span class="p">,</span> <span class="nb">p</span><span class="p">)</span>
<span class="vi">@title</span> <span class="o">=</span> <span class="n">t</span><span class="p">;</span>
<span class="vi">@author</span> <span class="o">=</span> <span class="n">a</span><span class="p">;</span>
<span class="vi">@published</span> <span class="o">=</span> <span class="nb">p</span><span class="p">;</span>
<span class="k">end</span>
<span class="k">def</span> <span class="nf">description</span>
<span class="s2">"</span><span class="si">#{</span><span class="vi">@title</span><span class="si">}</span><span class="s2"> by </span><span class="si">#{</span><span class="vi">@author</span><span class="si">}</span><span class="s2"> published in </span><span class="si">#{</span><span class="vi">@published</span><span class="si">}</span><span class="s2">"</span>
<span class="k">end</span>
<span class="k">end</span>
</code></pre>
<p>sometimes <br />
it all <br />
runs together</p>
<pre class="highlight plaintext"><code>
0100 class Book:
0200 attr_accessor :author, :title, :published
0300
0400 public Book(t, a, p) {
0500 title = t;
0600 author = a;
0700 year_published = p;
0800 }
0900 end
</code></pre>
<p>these dreams <br />
of code <br />
they are hell</p>
<pre class="highlight javascript"><code>
<span class="kd">var</span> <span class="nx">codeBook</span> <span class="o">=</span> <span class="nx">Book</span><span class="p">(</span><span class="s2">"Inferno"</span><span class="p">,</span> <span class="s2">"Dante"</span><span class="p">,</span> <span class="mi">1320</span><span class="p">);</span>
</code></pre>
<p>coding is my job <br />
five days a week <br />
i'm coding man</p>
<p>but i don’t want to code <br />
when i'm sleeping</p>
<p>i just want to sleep <br />
when i'm asleep</p>
<p>hell</p>
<pre class="highlight javascript"><code>
<span class="nx">pride</span> <span class="o">=</span> <span class="nx">Book</span><span class="p">.</span><span class="k">new</span><span class="p">(</span><span class="s2">"Pride and Prejudice"</span><span class="p">,</span> <span class="s2">"Austen"</span><span class="p">,</span> <span class="mi">1813</span><span class="p">)</span>
</code></pre>
<p>since i can't <br />
get away from the code <br />
i try to make it <br />
as easy as i can</p>
<p>after all <br />
i’m tired <br />
in fact i’m asleep <br />
life should be easy <br />
when i’m asleep</p>
<pre class="highlight fortran"><code><span class="w">
</span><span class="n">NOW</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">TIME</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span><span class="w">
</span><span class="k">CALL</span><span class="w"> </span><span class="n">MAKEEASY</span><span class="p">(</span><span class="n">NOW</span><span class="p">)</span><span class="w">
</span></code></pre>
<p>sometimes <br />
when i’m dreaming <br />
in code <br />
i make an array</p>
<pre class="highlight java"><code>
<span class="n">pride</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Book</span><span class="o">(</span><span class="s">"Pride and Prejudice"</span><span class="o">,</span> <span class="s">"Austen"</span><span class="o">,</span> <span class="mi">1813</span><span class="o">);</span>
<span class="n">war</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Book</span><span class="o">(</span><span class="s">"War and Peace"</span><span class="o">,</span> <span class="s">"Tolstoy"</span><span class="o">,</span> <span class="mi">1869</span><span class="o">);</span>
<span class="n">books</span> <span class="o">=</span> <span class="o">[</span><span class="n">pride</span><span class="o">,</span> <span class="n">war</span><span class="o">];</span>
</code></pre>
<p>and i let your code <br />
borrow my array</p>
<pre class="highlight java"><code>
<span class="n">your_nefarious_code</span><span class="o">(</span><span class="n">books</span><span class="o">);</span>
</code></pre>
<p>and your code <br />
changes my array</p>
<pre class="highlight java"><code>
<span class="c1">// Your nefarious code.</span>
<span class="kd">public</span> <span class="nf">your_nefarious_code</span><span class="o">(</span><span class="n">Book</span><span class="o">[]</span> <span class="n">books</span><span class="o">)</span> <span class="o">{</span>
<span class="n">zombies</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Book</span><span class="o">(</span><span class="s">"Pride and Prejudice and Zombies"</span><span class="o">,</span> <span class="s">"Grahame-Smith"</span><span class="o">,</span> <span class="mi">2009</span><span class="o">);</span>
<span class="n">books</span><span class="o">[</span><span class="mi">0</span><span class="o">]</span> <span class="o">=</span> <span class="n">zombies</span><span class="o">;</span>
<span class="o">}</span>
</code></pre>
<p>it's my array <br />
i didn't want you <br />
to change it</p>
<p>truth be told <br />
sometimes <br />
i do it to myself</p>
<pre class="highlight java"><code>
<span class="c1">// An honest mistake</span>
<span class="kd">public</span> <span class="nf">my_function</span><span class="o">(</span><span class="n">Book</span><span class="o">[]</span> <span class="n">books</span><span class="o">)</span> <span class="o">{</span>
<span class="n">jaws</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Book</span><span class="o">(</span><span class="s">"Jaws"</span><span class="o">,</span> <span class="s">"Benchley"</span><span class="o">,</span> <span class="mi">1974</span><span class="o">);</span>
<span class="n">books</span><span class="o">[</span><span class="mi">0</span><span class="o">]</span> <span class="o">=</span> <span class="n">jaws</span><span class="o">;</span>
<span class="o">}</span>
</code></pre>
<p>i have an excuse though <br />
i’m asleep</p>
<pre class="highlight ruby"><code>
<span class="c1"># Don't modify this code unless you are unconscious.</span>
</code></pre>
<p>this changing <br />
behind my back <br />
makes me <br />
thrash in my sleep</p>
<pre class="highlight ruby"><code>
<span class="k">def</span> <span class="nf">[]=</span><span class="p">(</span><span class="n">idx</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
<span class="k">raise</span> <span class="s2">"YouCantChangeMyArraySucker"</span>
<span class="k">end</span>
</code></pre>
<p>so in my dream <br />
i make <br />
a new rule <br />
no more <br />
changing arrays <br />
ever</p>
<pre class="highlight java"><code>
<span class="c1">// Your nefarious code foiled.</span>
<span class="c1">// Blam! Throws a YouCantChangeMyArraySuckerException!</span>
<span class="n">books</span><span class="o">[</span><span class="mi">0</span><span class="o">]</span> <span class="o">=</span> <span class="n">zombies</span><span class="o">;</span>
</code></pre>
<p>once i create an array <br />
that's it <br />
you can’t change it <br />
neither can i</p>
<pre class="highlight java"><code>
<span class="n">your_impossible_to_be_nefarious_code</span><span class="o">(</span><span class="n">books</span><span class="o">);</span>
</code></pre>
<p>now <br />
i don’t <br />
have to worry <br />
about your code or threads <br />
messing with my arrays</p>
<p>or my code <br />
or my threads <br />
it’s just easier</p>
<pre class="highlight plaintext"><code>
0600 REM I like zombies
</code></pre>
<p>but sometimes <br />
i need <br />
to change my array</p>
<pre class="highlight plaintext"><code>
GoTo 0000
</code></pre>
<p>but if i do<br />
i’m back to square one <br />
i don’t want to deal with it</p>
<pre class="highlight javascript"><code>
<span class="kd">function</span> <span class="nx">justLikeTheOldOneExcept</span><span class="p">(</span><span class="nx">a</span><span class="p">,</span> <span class="nx">i</span><span class="p">,</span> <span class="nx">x</span><span class="p">){</span>
<span class="nx">result</span> <span class="o">=</span> <span class="nx">a</span><span class="p">.</span><span class="nx">slice</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
<span class="nx">result</span><span class="p">[</span><span class="nx">i</span><span class="p">]</span> <span class="o">=</span> <span class="nx">x</span>
<span class="k">return</span> <span class="nx">result</span>
<span class="p">}</span>
</code></pre>
<p>so i'll let arrays make <br />
copies of themselves <br />
copies that are <br />
the same as the original</p>
<p>only different</p>
<pre class="highlight javascript"><code>
<span class="kd">var</span> <span class="nx">pride</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Book</span><span class="p">(</span><span class="s2">"Pride and Prejudice"</span><span class="p">,</span> <span class="s2">"Austen"</span><span class="p">,</span> <span class="mi">1813</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">war</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Book</span><span class="p">(</span><span class="s2">"War and Peace"</span><span class="p">,</span> <span class="s2">"Tolstoy"</span><span class="p">,</span> <span class="mi">1869</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">zombies</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Book</span><span class="p">(</span><span class="s2">"Pride & Prejudice & Zombies"</span><span class="p">,</span> <span class="s2">"Grahame-Smith"</span><span class="p">,</span> <span class="mi">2009</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">books</span> <span class="o">=</span> <span class="p">[</span><span class="nx">pride</span><span class="p">,</span> <span class="nx">war</span><span class="p">];</span>
<span class="kd">var</span> <span class="nx">other_books</span> <span class="o">=</span> <span class="nx">justLikeTheOldOneExcept</span><span class="p">(</span><span class="nx">books</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="nx">zombies</span><span class="p">);</span>
</code></pre>
<p>then i can have <br />
my old array <br />
and <br />
my new array</p>
<pre class="highlight fortran"><code><span class="w">
</span><span class="n">C</span><span class="w"> </span><span class="n">ZOMBIES</span><span class="w"> </span><span class="n">ARE</span><span class="w"> </span><span class="n">BACK</span><span class="w">
</span></code></pre>
<p>now i don't have to <br />
expend the effort <br />
to trust you</p>
<pre class="highlight plaintext"><code>
/* I trust me more than you. */
</code></pre>
<p>or me</p>
<pre class="highlight plaintext"><code>
/* I don't trust me. */
</code></pre>
<p>but sometimes you <br />
change my objects too</p>
<pre class="highlight java"><code>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">aNefariousBookMethod</span><span class="o">(</span><span class="n">Book</span> <span class="n">b</span><span class="o">)</span> <span class="o">{</span>
<span class="n">b</span><span class="o">.</span><span class="na">setTitle</span><span class="o">(</span><span class="s">"Dirk Gently's Holistic Detective Agency"</span><span class="o">);</span>
<span class="o">}</span>
</code></pre>
<p>sometimes i forget <br />
and change them myself</p>
<pre class="highlight java"><code>
<span class="c1">// Going about my sleepy business..</span>
<span class="n">Book</span> <span class="n">war</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Book</span><span class="o">(</span><span class="s">"War and Peace"</span><span class="o">,</span> <span class="s">"Tolstoy"</span><span class="o">,</span> <span class="mi">1869</span><span class="o">);</span>
<span class="n">aNefariousBookMethod</span><span class="o">(</span><span class="n">war</span><span class="o">);</span>
<span class="c1">// Wait what?</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">war</span><span class="o">.</span><span class="na">title</span><span class="o">);</span>
</code></pre>
<p>it’s been a long night <br />
so let’s have the same rules
for objects <br />
and arrays</p>
<pre class="highlight python"><code>
<span class="k">def</span> <span class="nf">justLikeTheOldOneExcept</span><span class="p">(</span><span class="n">v</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">copy</span><span class="p">(</span><span class="n">v</span><span class="p">)</span>
<span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">result</span><span class="p">,</span> <span class="nb">list</span><span class="p">):</span>
<span class="n">result</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">x</span>
<span class="k">else</span><span class="p">:</span>
<span class="nb">setattr</span><span class="p">(</span><span class="n">result</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">x</span><span class="p">)</span>
<span class="k">return</span> <span class="n">result</span>
</code></pre>
<p>no changing <br />
just modified copies</p>
<pre class="highlight java"><code>
<span class="n">Book</span> <span class="n">book1</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Book</span><span class="o">(</span><span class="s">"War and Peace"</span><span class="o">,</span> <span class="s">"Tolstoy"</span><span class="o">,</span> <span class="mi">1869</span><span class="o">);</span>
<span class="n">Book</span> <span class="n">book2</span> <span class="o">=</span> <span class="n">book1</span><span class="o">.</span><span class="na">justLikeTheOldOneExcept</span><span class="o">(</span>
<span class="s">"title"</span><span class="o">,</span>
<span class="s">"Dirk Gently's Holistic Detective Agency"</span><span class="o">);</span>
</code></pre>
<p>after all <br />
it's just a dream</p>
<pre class="highlight java"><code>
<span class="c1">// Rules are like spouses. There is an optimal number to have.</span>
</code></pre>
<p>now there are fewer <br />
rules to remember</p>
<p>sometimes i make an object <br />
with private fields</p>
<pre class="highlight java"><code>
<span class="kd">class</span> <span class="nc">Book</span> <span class="o">{</span>
<span class="kd">private</span> <span class="n">String</span> <span class="n">title</span><span class="o">;</span>
<span class="kd">private</span> <span class="n">String</span> <span class="n">author</span><span class="o">;</span>
<span class="kd">private</span> <span class="kt">int</span> <span class="n">year_published</span><span class="o">;</span>
<span class="c1">// ...</span>
<span class="o">}</span>
</code></pre>
<p>then i discover <br />
that i need <br />
to get at <br />
those private fields</p>
<pre class="highlight java"><code>
<span class="kd">class</span> <span class="nc">Book</span> <span class="o">{</span>
<span class="kd">private</span> <span class="n">String</span> <span class="n">title</span><span class="o">;</span>
<span class="kd">private</span> <span class="n">String</span> <span class="n">author</span><span class="o">;</span>
<span class="kd">private</span> <span class="kt">int</span> <span class="n">year_published</span><span class="o">;</span>
<span class="kd">public</span> <span class="n">String</span> <span class="nf">getTitle</span><span class="o">(){</span>
<span class="k">return</span> <span class="n">title</span><span class="o">;</span>
<span class="o">}</span>
<span class="kd">public</span> <span class="n">String</span> <span class="nf">getAuthor</span><span class="o">(){</span>
<span class="k">return</span> <span class="n">author</span><span class="o">;</span>
<span class="o">}</span>
<span class="kd">public</span> <span class="kt">int</span> <span class="nf">getYearPublished</span><span class="o">(){</span>
<span class="k">return</span> <span class="n">year_published</span><span class="o">;</span>
<span class="o">}</span>
<span class="o">}</span>
</code></pre>
<p>so i make them public</p>
<pre class="highlight fortran"><code><span class="w">
</span><span class="n">C</span><span class="w"> </span><span class="n">TOTAL</span><span class="w"> </span><span class="n">UP</span><span class="w"> </span><span class="n">THE</span><span class="w"> </span><span class="n">EFFORT</span><span class="w">
</span><span class="n">EFFORT</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">PRIVEFFT</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">PUBLEFFT</span><span class="w">
</span></code></pre>
<p>i had to make the <br />
private fields private <br />
and then i had to make <br />
the private fields public</p>
<p>that’s a lot of work <br />
and then it’s more work</p>
<pre class="highlight java"><code>
<span class="kd">class</span> <span class="nc">Book</span> <span class="o">{</span>
<span class="kd">public</span> <span class="n">String</span> <span class="n">title</span><span class="o">;</span>
<span class="kd">public</span> <span class="n">String</span> <span class="n">author</span><span class="o">;</span>
<span class="kd">public</span> <span class="kt">int</span> <span class="n">year_published</span><span class="o">;</span>
<span class="o">}</span>
</code></pre>
<p>it’s just easier to <br />
make all the fields public</p>
<p>after all <br />
why am i hiding from the data? <br />
don't hide from the data <br />
it's just data</p>
<pre class="highlight java"><code>
<span class="kd">class</span> <span class="nc">ThoseObjects</span> <span class="o">{</span>
<span class="kd">public</span> <span class="n">String</span> <span class="n">title</span><span class="o">;</span>
<span class="kd">public</span> <span class="n">String</span> <span class="n">author</span><span class="o">;</span>
<span class="kd">public</span> <span class="n">String</span> <span class="n">cityPublshed</span><span class="o">;</span>
<span class="kd">public</span> <span class="n">String</span> <span class="n">countryPublished</span><span class="o">;</span>
<span class="kd">public</span> <span class="kt">int</span> <span class="n">yearPublishd</span><span class="o">;</span>
<span class="kd">public</span> <span class="kt">int</span> <span class="n">editoon</span><span class="o">;</span>
<span class="kd">public</span> <span class="kt">int</span> <span class="n">copiesSold</span><span class="o">;</span>
<span class="o">}</span>
</code></pre>
<p>sometimes <br />
and there are <br />
lots of fields <br />
and i get tired of all the typing <br />
and my fingers make mistakes</p>
<pre class="highlight shell"><code>
git ci -m <span class="s1">'Fix misspelling of Book fields.'</span> Book.java
</code></pre>
<p>so i’ll just use a <br />
map or a hash or a dictionary <br />
or whatever we call it in this language <br />
and make an open <br />
name/value thing</p>
<pre class="highlight javascript"><code>
<span class="kd">var</span> <span class="nx">pride</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Pride and Prejudice"</span><span class="p">,</span> <span class="s2">"author"</span><span class="p">:</span> <span class="s2">"Austen"</span><span class="p">,</span> <span class="s2">"published"</span><span class="p">:</span> <span class="mi">1813</span><span class="p">};</span>
</code></pre>
<p>now i can make <br />
new objects full of data <br />
as fast as i can type <br />
which isn’t very fast <br />
since <br />
my eyes are closed</p>
<pre class="highlight javascript"><code>
<span class="kd">var</span> <span class="nx">zombies</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Pride and Prejudice and Zombies"</span><span class="p">,</span> <span class="s2">"author"</span><span class="p">:</span> <span class="s2">"Grahame-Smith"</span><span class="p">,</span> <span class="s2">"published"</span><span class="p">:</span> <span class="mi">2009</span><span class="p">};</span>
<span class="kd">var</span> <span class="nx">war</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"title"</span><span class="p">:</span> <span class="s2">"War and Peace"</span><span class="p">,</span> <span class="s2">"author"</span><span class="p">:</span> <span class="s2">"Tolstoy"</span><span class="p">,</span> <span class="s2">"published"</span><span class="p">:</span> <span class="mi">1869</span><span class="p">};</span>
</code></pre>
<p>if all my data <br />
is in <br />
hashes or <br />
dictionaries <br />
or maps <br />
whatever we call them <br />
in this language <br />
then i don’t have a place for my code</p>
<pre class="highlight java"><code>
<span class="kd">interface</span> <span class="nc">Function</span> <span class="o">{</span>
<span class="kd">public</span> <span class="n">Object</span> <span class="nf">invoke</span><span class="o">(</span><span class="n">Object</span> <span class="n">arg</span><span class="o">);</span>
<span class="o">}</span>
<span class="kd">class</span> <span class="nc">MakeDescription</span> <span class="kd">implements</span> <span class="n">Function</span> <span class="o">{</span>
<span class="kd">public</span> <span class="n">Object</span> <span class="nf">invoke</span><span class="o">(</span><span class="n">Object</span> <span class="n">arg</span><span class="o">)</span> <span class="o">{</span>
<span class="n">Book</span> <span class="n">book</span> <span class="o">=</span> <span class="o">(</span><span class="n">Book</span><span class="o">)</span><span class="n">arg</span><span class="o">;</span>
<span class="k">return</span> <span class="n">book</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"title"</span><span class="o">)</span> <span class="o">+</span>
<span class="s">" by "</span> <span class="o">+</span>
<span class="n">book</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"author"</span><span class="o">)</span> <span class="o">+</span>
<span class="s">" published in "</span> <span class="o">+</span>
<span class="n">book</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"yearPublished"</span><span class="o">);</span>
<span class="o">}</span>
<span class="o">}</span>
</code></pre>
<p>so i’ll just make
little <br />
one method <br />
no data <br />
objects <br />
and put my code there</p>
<p>i’ll call these things <br />
functions <br />
that’s a word i learned in <br />
math class <br />
before i feel asleep</p>
<pre class="highlight javascript"><code>
<span class="kd">var</span> <span class="nx">make_description</span> <span class="o">=</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">b</span><span class="p">){</span>
<span class="k">return</span> <span class="nx">b</span><span class="p">.</span><span class="nx">title</span> <span class="o">+</span> <span class="s2">" by "</span> <span class="o">+</span> <span class="nx">b</span><span class="p">.</span><span class="nx">author</span>
<span class="s2">" published in "</span> <span class="o">+</span> <span class="nx">b</span><span class="p">.</span><span class="nx">published</span>
<span class="p">};</span>
</code></pre>
<p>but before the night was over <br />
<a href="/articles/2018/04/16/fun-dreams2.html">the dream continued</a></p>
<p>– Russ</p>
<blockquote>
<p><em>A version of this article originally appeared on <a href="http://cognitect.com">Cognitect blog</a>.</em></p>
</blockquote>
Start Simplehttp://russolsen.com/articles/2018/04/12/ex-030-start-simple.html2018-04-11T20:00:00-04:002018-04-22T13:40:56-04:00Article Author<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>Sometimes the hardest part of an explanation is knowing where
to start. For example, I’ve spent a lot of my career teaching
programmers who are familiar with one programming language,
frequently Java, a new programming language, maybe Ruby or Clojure.</p>
</div>
<div class="paragraph">
<p>The challenge in teaching programming languages is that even a moderately
successful programming language is sprawling technical and social artifact:
At its core, every programming language has the code that translates
the programmer’s instructions into instructions that a CPU
can act on. But if the language is at all popular you will also
have a rich ecosystem of utilities and tools. And around that you
will have a community of programmers who, over time, will come up
with sometimes conflicting best practices.</p>
</div>
<div class="paragraph">
<p>So now imagine you are standing in the front of a room full of
people who are looking to you to introduce them to all of this.
Where do you start?</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_start_with_a_lie">Start With a Lie!</h2>
<div class="sectionbody">
<div class="paragraph">
<p>I generally start by lying my butt off. For example, when I’m
<a href="https://pragprog.com/book/roclojure/getting-clojure">introducing the Clojure programming language</a>,
early on we will start seeing things in our programs that look
like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="clojure">[<span class="integer">1</span> <span class="integer">2</span> <span class="integer">3</span> <span class="integer">4</span>]</code></pre>
</div>
</div>
<div class="paragraph">
<p>Ask just about any programmer from any language background what
that is and they will say <em>That’s an array</em>.</p>
</div>
<div class="paragraph">
<p>Unfortunately
the Clojure thing above
is not really an array. Yes, it does represent an ordered collection of
(in this case four) items. Yes, you can easily find out how many
items there are — just call the <code>count</code> function.
And yes, you can index into it with an
integer and get the second or the fourth element very quickly.
But unlike a traditional array, which is backed by a continuous block of mutable memory, a Clojure <em>vector</em> — to give these values their proper name — is a sophisticated immutable data structure organized more like a tree than a block of memory.</p>
</div>
<div class="paragraph">
<p>That’s all true, but when I’m just starting out with a group of neophyte
Clojure programmers, I say
<em>This thing with the square brackets is called a vector. For
now you can think of it as an array.</em> And then I move on.</p>
</div>
<div class="paragraph">
<p>But didn’t I just say it <em>wasn’t</em> an array? I did, but it doesn’t matter: When you are trying to get an explanation
off the ground it’s OK to start with a simplified version of reality.
The idea is that you kick things off with the cartoon version of reality and later, after your listener has
a bit more context and is feeling more comfortable with the
subject you can circle back and fill out the picture.</p>
</div>
<div class="paragraph">
<p>You can think of this approach as the successive approximation explaining technique. You start with a rough sketch of real life: <em>It’s an array</em>.
Then you move on to the next topic, possibly simplifying that as well.
You keep doing that until you have gotten across a cartoon version of
the whole topic. Once you done that you go back and start filling in
the details, correcting the lies to a listener who is now prepared to
understand the nuances.</p>
</div>
<div class="paragraph">
<p>So with Clojure I start by saying <em>Vectors are (more or less) arrays.</em>
Then I go
on to the other Clojure data structures and then to how all of the Clojure
data structures are immutable but can make very fast, modified copies
of themselves. And <em>then</em> I circle back to why that thing with the square
brackets is different — and more — than a simple array.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_progressive_idea_loading">Progressive Idea Loading</h2>
<div class="sectionbody">
<div class="paragraph">
<p>These kinds of <em>Start Simple</em> explanations are something like
the progressively loading images that you see on web pages, the ones that initially get downloaded
as blurry blobs and then are slowly refined into the full resolution image — Typically of a cute cat. You start with a blurry but digestible explanation and once that is in place you start refining it.</p>
</div>
<div class="paragraph">
<p>The trick to pulling off the <em>Start Simple</em> plan is to come up with
a cartoon version of your subject that is both internally consistent
and within striking distance of what your listener already knows.</p>
</div>
<div class="paragraph">
<p>Thus when I kick off an explanation of Clojure I generally start by
presenting it as a conventional programming language, which it is
emphatically not. But I plow ahead, talking about how you name things,
how you define functions and organize how your code into files.
Along the way I say
<em>Oh those vector thing, they’re sort of arrays.</em>
Once my listener has the general lay of the Clojure land I go back
and start pointing out the things that makes Clojure an
unconventional programming language — the syntax, the focus on functions
and most of all the immutable data structures. Which brings us right
back to the reason vectors are not really arrays, at which point I’m
hoping that my listener has enough grounding in the basics to understand
the next level of detail.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_beware_the_angry_expert">Beware the Angry Expert</h2>
<div class="sectionbody">
<div class="paragraph">
<p>If you do employ the <em>explanation by successive approximation</em> technique
sooner or later you will run into an outraged expert.
like this: You are happily telling your listener that this <code>[1 2 3 4]</code>
is, more or less, and array. And a person expert in the field — in this case Clojure — will over hear you and bellow:</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>THAT IS NOT AN ARRAY!!!!!!!!</p>
</div>
</blockquote>
</div>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>YOU DON’T KNOW WHAT YOU ARE TALKING ABOUT
THAT IS A SOPHISTICATED TREE BASED IMMUTABLE DATA STRUCTURE…​</p>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>The thing to do in these situations is to smile stupidly, thank the expert
for his or her input
and go right back to saying <em>more or less an array</em>.</p>
</div>
<div class="paragraph">
<p>The world is full of
people who are expert in X but have no idea how to explain X. The trouble
with experts is that they have a tendency to try to explain
everything at once.
But if you try to explain everything at once you are likely to end
up explaining nothing at all, permanently.
So smile and ignore the experts, at least
to the point of not trying to get every detail accurate up front.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_wrapping_up">Wrapping Up</h2>
<div class="sectionbody">
<div class="paragraph">
<p>So there you have another explaining plan: Start by explains a simple, cartoon
version of the real world, just enough to ground your listener in the subject.
To put it bluntly, you lie. Just a little.
Then roll back and start filling in the details, untelling the lies one by one.</p>
</div>
<div class="paragraph">
<p> — Russ</p>
</div>
</div>
</div>From the Tophttp://russolsen.com/articles/2018/04/11/ex-020-from-the-top.html2018-04-10T20:00:00-04:002018-04-22T13:40:49-04:00Article Author<div id="preamble">
<div class="sectionbody">
<div class="imageblock">
<div class="content">
<img src="/images/helicopter.jpg" alt="Leonardo da Vinci helicopter.">
</div>
</div>
<div class="paragraph">
<p>In the last article we saw if you building, creating, designing or developing things is your first job then explaining those things is job two. And three. And four. Look at it this way: If you can’t explain it, sooner or later someone is going to decide that this <em>thing</em> is just too much trouble to keep around and toss it.
And it’s not just the stuff you build. Explaining is a key way that you can make the people around you more effective, your company more efficient and your work life more interesting.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_have_a_plan">Have a Plan</h2>
<div class="sectionbody">
<div class="paragraph">
<p>If you do want to improve your explaining chops
then you need to start
with the one thing that every explanation has:
A plan.
Since every explanation is a package of transportable facts
that you are trying to copy into the
head of your listener, every single explanation is built according to some plan. The plan may be well thought out or just cobbled together but there will be a plan. A carefully planned explanation is like a
Leonardo da Vinci drawing or a Dutch masters' paintings, enjoyable <em>and</em> functional.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="/images/picasso-detail.png" alt="Still life with a bottle of rum" width="Picasso" height="detail.">
</div>
</div>
<div class="paragraph">
<p>Even if you don’t consciously plan your explanation, it will still have a plan,
what I think of as the default plan.
Instead of laying out the important ideas and facts in a logical sequence,
with the default plan you take more of a stream of consciousness approach.</p>
</div>
<div class="paragraph">
<p>If you are a software developer and you are called on to explain the system you are working on, you might start with the last feature you worked on. Or the first. Of the part of the system you like the best. Or the least. Or the part that was going to be so cool but was cancelled. Or the part that always seizes up in production. All of which may be interesting — and possibly entertaining — but is probably not going to jell into an effective explanation.
Like a Picasso painting, all of the parts may or may not be there, but what is certain is that they will be jumbled together into a hard to decipher whole.</p>
</div>
<div class="paragraph">
<p>As I say, you need a plan.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_lead_with_the_big_picture">Lead With the Big Picture</h2>
<div class="sectionbody">
<div class="paragraph">
<p>So if you want to avoid the Picasso style explanation you need to
do a little bit of planning. This can be as simple as pausing to take
a breath in the hallway before you jump into an explanation of <em>how this
thing works</em>. During that breath you might decide to go for the <em>top down</em> layout for you explanation.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="/images/zoomin.jpg" alt="Zoom In!">
</div>
</div>
<div class="paragraph">
<p>Imagine you are working with a developer who is new to your project and
the two of you are going to tackle the next development task — perhaps
you need to build a login screen. How do you orient your partner? If
follow the top-down plan then you start with the big picture:</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>We are, of course, trying to get rich selling pet food on the Internet…​</p>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>And then zoom in a bit:</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>So we are building this e-commerce site…​</p>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>And then finally:</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>And so we need a login screen which can deal with either a password, finger or paw print authentication…​</p>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>None of this is rocket science — it just requires a bit of planning and thought. You start with the big picture, which provides the context, the setting for for your explanation and then you work down to the details.</p>
</div>
<div class="paragraph">
<p>I was recently reminded of the value of a top down explanation when I
happened to mention at a party that I was in building a 3D printer in
my spare time. Instead the <em>oh that’s cool</em> excitement I was expecting, I got
a number of blank stairs. It was then that I realized that perhaps not
everyone knows what a 3D printer is. No problem, you just need to zoom out
a little bit and start with the big picture:</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>So a 3D printer is a gadget for creating most anything that is reasonably
small and made of plastic. They work by depositing thin layers of
molten plastic on a glass plate. They are about the size of a an
ordinary <em>print text on paper</em> printer and are driven by a computer
in pretty much the way an ordinary printer is.</p>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>That’s the big picture, and now it’s time to zoom in:</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>So I have been building a 3D printer on my dinning room table…​</p>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>And then everyone can be properly thrilled by my stories of motors and
belts. Or at least they won’t be completely confused by them.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_the_best_top_dow_explanation_ever">The Best Top Dow Explanation Ever</h2>
<div class="sectionbody">
<div class="paragraph">
<p>While my little tale of 3D printing is a decent top down explanation,
my favorite example actually comes from the most famous speech in
US political history, the Gettysburg Address. Lincoln delivered
that speech at the height of the US Civil War and famously — at least if
you are an American — it starts with these words:</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>Four score and seven years ago our fathers brought forth on this continent, a new nation conceived in Liberty, and dedicated to the proposition that all men are created equal.</p>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>Don’t let the archaic language distract you. Lincoln is starting with
the big picture by going back to the founding of the United States
(for him) 87 years previous.</p>
</div>
<div class="paragraph">
<p>He then zooms in a bit by focusing on the last few years:</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>Now we are engaged in a great civil war, testing whether that nation..
can long endure…​</p>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>And then finally to this afternoon, right now:</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>We are met on a great battle-field of that war.
We have come to dedicate a portion of that field, as a final resting place for those who here gave their lives that that nation might live.</p>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>That is the entire history of the US from the beginning to today in a single paragraph. That is a first class top down explanation.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_or_you_can_reverse_the_neutron_polarity">Or You Can Reverse the Neutron Polarity</h2>
<div class="sectionbody">
<div class="paragraph">
<p>A second way that you can organize an explanation is to reverse the flow
of the top-down explanation and go from the details to the bigger picture. So you start in the weeds:</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>Here we are, working login screen which can deal with either a password, finger or paw print authentication…​</p>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>And then work outward:</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>Because our e-commerce site needs a log in screen…​</p>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>And finally the big picture:</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>Because we are trying to get rich selling pet food on the Internet…​</p>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>It doesn’t matter which direction you do it, what does matter is that you
connect the messy details, a log in screen for example, to the more global picture. You need to do this because it’s the <em>context</em> that is the critical thing that every good explanation provides. Look at it this way: All I have to do is reach for my browser and I have a billion individual facts at my fingertips. The thing a good explanation provides is how the facts fit together. Not just how a 3D printer works or where the password field should go but <em>what</em> a 3D printer is for and <em>why</em> we are creating the login screen.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_wrapping_up">Wrapping Up</h2>
<div class="sectionbody">
<div class="paragraph">
<p>So there you have it. You need a plan for your explanations, because if you don’t have a plan you explanation is likely to come out looking like abstract art: Lovely perhaps, but less than informative. So in this article we looked at top down and bottom up explanations. Either start with the big picture and work down to the details or start with the details and work up. The idea is to anchor the details in a context that makes sense to your listener.</p>
</div>
<div class="paragraph">
<p>Happily, top down and bottom up are not the only items on the explanation plan
menu and so in the next couple of articles we will look at process and simple to complex explanations.</p>
</div>
<div class="paragraph">
<p> — Russ</p>
</div>
</div>
</div>