codeless_code 0.1.2

data/data/the-codeless-code/en-qi/case-171.txt

@@ -0,0 +1,79 @@
+Date: 2014-11-30
+Number: 171
+Title: Initial Conditions
+Names: Banzen, Hwídah, Djishin
+Topics: production support, clues, SQL, dynamically-generated SQL
+Geekiness: 3
+Illus.0.src: detective.jpg
+Illus.0.title: Does anyone else think it's weird that the universal search icon is a magnifying glass?  When was the last time you searched for *anything* with a magnifiying glass in real life?  My ideal search icon would be a little picture of me, screaming "HAS ANYONE SEEN MY CAR KEYS?!"
+
+
+The nun [[Hwídah]] was summoned to the offices of master
+[[Banzen]].  She found the master waiting with his
+apprentice [[Djishin]] in attendance.
+
+Banzen said, "A happy day for you, little nun!  Since you
+take such pleasure in learning hidden truths and seeing
+guilty parties corrected, I have an entertaining task for you."
+
+"I serve at the pleasure of the Temple, not my own," Hwídah
+replied with a dutiful bow.  But her stomach was already
+clenched; for no doubt this was the start of her
+punishment for [[#152|trespassing on forbidden Temple ground.]]
+
+"An infrequent but stubborn error has plagued the
+[[Elephant's Footprint Clan]] for some time now," said the
+master as he handed the nun a printout.  "Our database logs
+show this malformed SQL query, yet a thorough
+search of our code base reveals no such query anywhere.
+Find the source.  I give you one week."
+
+Hwídah studied the paper.  "A few minutes should suffice.
+May I borrow the master's terminal?"
+
+Banzen's eyebrows shot up.  He exchanged glances with his
+apprentice, then slid his laptop toward the nun.
+
+Hwídah consulted the printout, typed something, scrutinized
+the screen, consulted the printout again, and so on several
+times over.  "There," she said finally, turning the screen
+around.  The cursor was indeed hovering over a SQL fragment
+with a missing right parenthesis.  "If I return to my
+workstation, I can trace this code to its consumers and
+reproduce the error seen in the logs.  Then we may repair
+the defect with confidence."
+
+"Go," said Banzen to Hwídah.
+To his apprentice he said: "Observe."
+
+- - -
+
+As the pair walked to Hwídah's cubicle, Djishin whispered,
+"The speed of your diagnosis was surprising."
+
+"A simple matter," said Hwídah, handing the printout to the
+monk.  "The malformed query begins with <tt>WHERE 1=1</tt>.
+That has the stink of dynamically-generated SQL -- for
+although the initial condition is trivial, its <tt>TRUE</tt>
+value allows a developer to append any number of
+/real/ conditions as simple <tt>AND</tt> clauses.  I have
+used this technique myself when implementing search forms
+with optional fields.  Once I recognized it, I merely
+searched our code for the individual <tt>AND</tt> clauses."
+
+"You misunderstand me," said Djishin.  "I was not surprised
+that you were /able/ to solve it immediately; I was
+surprised that you did so despite being given a full week.
+That has the stink of ambition -- for although this initial
+problem was trivial, your ready truthfulness
+now allows my master to entrust you with any number of /real/
+problems."
+
+Hwídah sighed.  "It is just as well.  If I had pretended
+that this problem was difficult enough to merit days of
+effort, Banzen would have thought me either deceitful or
+incompetent.  Neither would sit well with me.  That is what
+he truly wished to discover."
+
+Djishin nodded.  "Sometimes a test serves a purpose
+/because/ the answer is so obvious."

data/data/the-codeless-code/en-qi/case-172.txt

@@ -0,0 +1,48 @@
+Date: 2014-12-07
+Number: 172
+Title: Lesson One
+Names: Jinyu, Kaimu
+Topics: teaching, mentoring, communication, failure, improvement
+Geekiness: 0
+Illus.0.src: apple.jpg
+Illus.0.title: Nature will often use a dumped core to start a child process.
+
+[[Jinyu]], the ancient Abbess Over All Clans And Concerns,
+summoned young master [[Kaimu]] to her presence.
+
+"A dozen students from the Western Heap are staying in the
+village below," said Jinyu.  "They have yet to choose a
+vocation and they are curious about programming.  Go, spend
+the week with them, teach them something."
+
+Kaimu did this gladly, for he had long wished to foster in
+others his own love of the Art of Unseen Engines.
+
+After the week's end he was summoned again to Jinyu's
+presence.  She held in her wrinkled hands a sheaf of letters
+with familiar purple postal-marks.  "What word from the
+students of the Western Heap?" asked Kaimu.
+
+Jinyu whacked the master on the head with her umbrella.
+"All have reported unfavorably.  Your speech was too rapid,
+your slides were too terse, your gestures distracting, your
+examples inane, and you gave no bathroom breaks.  In the
+rare moments when you were not tedious or garrulous, you
+were utterly incomprehensible.  None thought the class worth
+their while."
+
+Kaimu was aghast.  "Did no one learn anything?"
+
+In answer, Jinyu whacked him on the head again.  "What now
+may be said of Kaimu?"
+
+"That he cannot teach," said Kaimu miserably.
+
+Jinyu nodded in satisfaction.  "Then one thing has been learned."
+
+When Kaimu bowed and turned to go, Jinyu stopped him and
+said: "From one apple seed a fool makes only a bitter meal,
+but the gardener may grow a sweet harvest.  Go, find your
+shovel."
+
+Kaimu was comforted.

data/data/the-codeless-code/en-qi/case-173.txt

@@ -0,0 +1,84 @@
+Date: 2014-12-21
+Number: 173
+Names: Eku, Mugen
+Topics: poetry, TCP, IP, HTTP, network, sockets, protocols, clients, servers
+Geekiness: 3
+Title: Lost Peer
+
+
+<i>From "The Courtship of Eku and Mugen":</i> {{1}}
+
+There was a time, as ancient logs recall, //
+when you and I would Handshake every morn //
+through packets on an Ether-network borne //
+our love conveyed by formal Protocol.
+
+So high was your availability, //
+a timeout span in minutes would I set -- //
+secure that neither POST nor PUT nor GET //
+would e’er a 504 return to me.
+
+And when your subnet’s firewall arose, //
+you bade its router map a secret port //
+through which we could clandestinely consort -- //
+a backdoor assignation, undisclosed.
+
+Discreetly you’d a server-socket bind //
+to listen at your gate for my connect //
+But if this host address be still correct, //
+Then why resounding silence do I find?
+
+My every last connection is refused, //
+my buffered input streams have all run dry, //
+the root nodes of our JSON trees I spy //
+now withered on the heap; they die unused.
+
+Oh! Where can you have gone, beloved peer? //
+A segmentation fault?  A kill-dash-9? //
+No, say you live!  And if the fault be mine, //
+I'll every line rewrite 'til you appear.
+
+'Til then /i/ iterate from one to /n/ //
+Yet never take exception when I fail //
+but catch myself, and log, and weep, and wail, //
+then sleep an interval, and try again.
+
+Thus furtively alone at night I'll SYN //
+and dream that you will send some answer back -- //
+Oh, SYN with me!  And promise we shall ACK //
+until we both lie sated, kiss... and FIN.
+
+I'll seek thee there with netcat minus-z! //
+I'll seek thee here with netstat minus-t! //
+Let others mock my hopeless loyalty -- //
+They only serve who serve HTTP.
+
+
+
+== Qi's Commentary
+
+Mugen liked to code in poetry.  Presumably, the seventh stanza
+is meant to convey an algorithm like this:
+
+<pre>
+    SocketAddress sockAddr = new InetSocketAddress(host, port);
+    for (int i = 1; i <= N_TRIES; i++) {
+        try {
+            client.connect(sockAddr, TIMEOUT_MILLIS);
+            return client;
+        }
+        catch (Exception e) {
+            log.warning("weep, wail");
+            Thread.sleep(INTERVAL_MILLIS);
+        }
+    }
+    throw new IOException("give up");
+</pre>
+
+It is theorized that his ten-thousand-stanza epic, /The Dromedary/,
+describes a Perl-to-OCaml converter written in C++.
+No scholar can stay sane long enough to be certain.
+
+
+{{1}} Dedicated to Stanislaw Lem, with profuse apologies{{2}} to my translators.
+{{2}} Guys, please don't kill me for this.  Really, you can skip this one.

data/data/the-codeless-code/en-qi/case-174.txt

@@ -0,0 +1,83 @@
+Date: 2014-12-28
+Number: 174
+Names: Banzen, Suku, Zjing, Spider Clan
+Topics: improvement, career, changes, courage, change, experience
+Geekiness: 0
+Title: Out of the Zone
+
+The nun [[Zjing]] had a well-known [[#54|fear of heights]].
+For this reason she lived in the valley far below the mountaintop
+temple, and had only braved the treacherous cliffside paths
+[[#136|but once]].  Through webcams, phone and IM she had maintained
+an effective telepresence in the Temple.
+
+So it was with some trepidation that she received this email
+from master [[Banzen]] on the evening of the longest night
+of winter:
+
+  An important Temple matter has arisen, and I desire your
+  confidential input.
+
+  My schedule has an opening tomorrow when the dawn bell is struck.
+  We may converse electronically if you so desire, but I would prefer
+  to speak in person in my office.
+
+  B.
+
+
+In darkness Zjing dutifully ascended the first of the steep
+stairs that had been hewn out of the mountain walls.  Higher
+and higher she climbed, trying hard not to let her gaze fall
+to the wintry foothills below.  Snowdrifts blocked her path;
+she scrambled over them.  Rope bridges creaked underfoot;
+she crossed them.  Great moonlit icicles trembled overhead,
+tall as trees, sharp as spears, threatening to fall at the
+slightest whisper; she edged past them without a sound.
+Howling winds threatened to tear her off the foot-wide path
+and return her to the valley quickly and permanently; she
+clung to the rock face and forced herself to continue,
+hand-hold by miserable hand-hold.
+
+At the last echo of the dawn bell, Zjing appeared
+at Banzen's door.  She bowed and entered, betraying no emotion.
+
+Banzen closed the door behind her.  "I have just heard from
+master [[Suku]]," he said.  "Although she was to return to us
+this winter, she has decided instead to remain in the
+Far Provinces."
+
+"Does she no longer love our Temple?" asked Zjing.
+
+"It is /because/ she loves our Temple that she will not
+return yet," said the master.  "She has found her travels to
+be surprisingly edifying, both for herself and her
+apprentices.  True, they are weary and weathered, and the
+comforts of home would be most welcome now.  But there is
+much more to teach and to learn.  If Suku extends her
+travels, all will benefit greatly in the end."
+
+"This past year has been most difficult for the [[Spider Clan]]
+without her guidance," said Zjing.
+
+"Indeed," agreed Banzen. "A replacement must be trained.
+As a senior nun of that clan, I called you here to learn
+who you would suggest."
+
+"Can one /train/ a monk to be a master?"
+
+Banzen chuckled.  "Did you think that I was born with this
+title?  In our Temple, /master/ is not an honorific, but a
+verb disguised as an adjective.  The candidate becomes by
+learning, and learns by doing."
+
+Zjing pondered the many senior monks she knew.
+All had virtues to speak of, but vices as well.
+"What qualities are you most looking for in such a
+candidate?" she asked at last.
+
+"The first quality is the same one that master Suku herself
+has demonstrated," said Banzen.  He walked over to his
+window and gazed across the gorge.  The thin light of dawn
+was just now illuminating the last few zig-zags of the steep,
+terrible path up from the valley.  "The first quality is a
+willingness to leave one's comfort zone when duty calls."

data/data/the-codeless-code/en-qi/case-175.txt

@@ -0,0 +1,72 @@
+Number: 175
+Date: 2015-01-01
+Title: Flat Shark
+Geekiness: 2
+Names: Kaimu
+Topics: Java, single-responsibility principle, naming, interfaces, multiple inheritance, delegation, composition, modelling, object-oriented programming
+Illus.0.src: shark.jpg
+Illus.0.title: Ceci n'est pas une peinture.
+Illus.0.par: 1
+
+A monk asked Java master [[Kaimu]]: //
+What is the "single-responsibility principle"?
+
+Said Kaimu: //
+That a class shall do exactly one thing, //
+and do it completely.
+
+The monk asked: //
+How shall I decide this "one thing"?
+
+Said Kaimu: //
+The Fisherman does not build ships, //
+or we would call him a Shipwright.
+
+The monk asked: //
+Is there no room in your philosophy for interfaces? //
+What if my class can serve as a Fisherman, //
+and a Shipwright and Sailor besides?
+
+Said Kaimu: //
+What would you name such a three-headed monster?
+
+The monk replied: //
+Shísho, after my uncle.  He lives by the sea and does all these things.
+
+Said Kaimu: //
+I would give your class Shísho three instance variables: //
+a Fisherman, a Shipwright, and a Sailor. //
+Then Shísho may implement those interfaces by delegation.
+
+The monk replied: //
+I speak of inheritance, yet you answer in composition. //
+/All/ of my uncle is a Fisherman, not just his left foot. //
+What use are objects, if we do not faithfully model the world?
+
+Said Kaimu: //
+If I paint a fine shark upon this page, will you say, "Fine shark!" //
+or will you complain that it is flat and does not eat you? //
+
+The monk asked: //
+But how are we to know when the flat shark is shark enough? //
+Or when our uncle should fish with his left foot?
+
+Said Kaimu: //
+Learning how is /our/ "single reponsibility".
+
+
+== Qi's Commentary
+
+Every class does exactly one thing -- //
+but sometimes that one thing //
+is "doing too many things".
+
+
+== Qi's Poem
+
+One morning Kaimu took up his brush. //
+In two strokes he painted an exquisite shark. //
+A passerby laughed. "It is a poor shark that can't open its mouth!" //
+Kaimu replied, "Even so, it has told me that you are a fool."
+
+

data/data/the-codeless-code/en-qi/case-176.txt

@@ -0,0 +1,68 @@
+Date: 2015-01-11
+Number: 176
+Title: Many Happy Returns
+Names: Kaimu
+Topics: return statements, error handling, readability, efficiency, single-entry single-exit, C, assembly language
+Geekiness: 2
+Illus.0.title: The rice is also cold.
+
+
+A novice monk said to master [[Kaimu]], "I have heard that it is
+preferable to have only one return statement in a
+function.  Do you agree?"
+
+Kaimu asked, "Where is your bowl?"
+
+The monk apologized and left to fetch his bowl.
+
+- - -
+
+When the monk returned, he showed his bowl to the master
+and said, "I have heard that it is preferable to have
+only one return statement in a function.  Do you agree?"
+
+Kaimu asked, "Why is there no rice in your bowl?"
+
+The monk apologized and left to fetch some rice.
+
+- - -
+
+When the monk returned, he showed his bowl full of steaming
+white rice to the master and said, "I have heard that it is
+preferable to have only one return statement in a
+function.  Do you agree?"
+
+Kaimu took the monk's bowl and placed it on his
+desk.
+
+"You speak of a most venerable design principle, known as
+/Single-Entry Single-Exit/," said the master.  He then told
+the monk of the glorious days of coding long past, when
+memory was low, hardware was slow, and resources had to be
+managed with care.  "For C did you no favors," said Kaimu,
+"and Assembly did half as many as that.  So if your function
+borrowed a thing, then your function had to put it back.
+And how was this most easily done?  By putting all the
+cleanup code in one place, at the function's bottom... a
+tradition that continues to this day."
+
+Kaimu then spoke of the birth of objects, of destructors and
+finalizers.  He spoke of garbage collection too; of
+reference counting and mark-and-sweep, and compilers that
+could tell when an object went out of scope.  He
+spoke of buffers that grew as needed and vanished when not,
+of files that closed themselves, of connection
+pools and thread pools and try-with-resources, and of how
+wondrous and magical was the modern bestiary of languages,
+where monks could devote their energies to more interesting
+problems instead of fussing about with <tt>malloc</tt> and
+<tt>free</tt> and <tt>goto fail</tt>.
+
+"Yes," said the weary monk at last.  "But do you /agree/
+with the design principle of Single-Entry Single-Exit, or do
+you /not/?"
+
+Kaimu looked down and said, "Why is the rice in your bowl
+white, and not brown?"
+
+

data/data/the-codeless-code/en-qi/case-177.txt

@@ -0,0 +1,98 @@
+Date: 2015-01-19
+Number: 177
+Title: The Tool-Shed
+Names: Djishin, Banzen
+Topics: reuse, abstraction, APIs, bloat, YAGNI
+Geekiness: 2
+
+The monk [[Djishin]] was walking in the forest, when he
+came upon a man sawing wood by the edge of the path.
+
+"What are you making, friend?" asked Djishin.
+
+"A tiny tool-shed that I have sorely needed," said the man.
+"It will have one hook for my rake, another for my spade,
+and a place on the floor for my tin pail."
+
+Djishin wished the man good health and continued on his way.
+
+- - -
+
+The next day Djishin came upon this same man sawing wood.
+Many posts had been set into the ground.
+
+"How goes your work today, friend?" asked Djishin.
+"That is a wider tool-shed than I'd imagined."
+
+Said the man, "Last night I wondered: what if I buy more
+rakes or pails, or wish to store clay pots?  So now it is a
+proper garden-shed.  See, here will go a window, with a
+shelf to start my seedlings."
+
+Djishin wished the man good health and continued on his way.
+
+- - -
+
+The next day Djishin came upon this same man sawing wood.
+Many more posts had been set into the ground, and joists for
+a floor, and ceiling beams.
+
+"How goes your work today, friend?" asked Djishin.
+"That is a taller garden-shed than I'd imagined."
+
+Said the man, "Last night I thought: if I add
+a second storey, it would make a cozy cottage where I could
+rest after a hard day's gardening.  See, here will go a ladder,
+where I may climb to a loft with a humble bed."
+
+Djishin wished the man good health and continued on his way.
+
+- - -
+
+The next day Djishin came upon this same man sawing wood.
+Many more posts had been set into the ground, and ceiling
+beams, but the floor had been torn apart.
+
+"How goes your work today, friend?" asked Djishin.
+"That is a larger cottage than I'd imagined."
+
+Said the man, "Last night I decided: stairs are better than
+a ladder, for under them one may keep clothes and shoes.  In
+which case I may as well build a proper house, with a
+kitchen and a bathing-room, and give it to my son when he is
+grown.  See, here will go a fine stone floor, when I have
+money to pay the quarry."
+
+Djishin wished the man good health and continued on his way.
+
+- - -
+
+The next day Djishin came upon this same man sawing wood.
+Still more posts had been set into the ground, with
+rickety catwalks between them.  From the ceiling beams hung
+ropes and pulleys.
+
+"How goes your work today, friend?" asked Djishin.
+"That is a grander house than I'd imagined."
+
+Said the man, "Last night I realized: my son may someday
+wish a wife and family.  So I am putting all in readiness for
+an estate of any size, depending on the number of children
+he foresees.  See, here are the ramps to carry flagstones
+for the floor, and scaffolding he can climb to set the roof
+tiles."
+
+Djishin wished the man good health and continued on his way.
+
+- - -
+
+The next day Djishin was at his terminal when master [[Banzen]]
+came in.
+
+"How goes your work today, monk?" asked Banzen.
+"I expect you need more time to implement this grand email
+framework you devised last week."
+
+"No more time," said Djishin, swivelling his monitor to face
+the master.  "I have dismantled the bones of my estate, and
+built for you this fine tool-shed."

data/data/the-codeless-code/en-qi/case-178.txt

@@ -0,0 +1,68 @@
+Date: 2015-01-25
+Number: 178
+Title: Unity
+Names: Landhwa, Wangohan, Zjing
+Topics: constants, classes, abstraction, big ball of mud, coding style, Java, coopertation, magic constants, refactoring
+Geekiness: 3
+
+A nasty stomach flu had been making its way through the
+Temple.  Fully half the [[Spider Clan]] had fallen victim,
+so to meet deadlines the monk [[Wangohan]] had been forced
+to team with his longtime nemesis, the monk [[Landhwa]].
+
+To avoid conflicts that might lead to
+[[#84|yet another incapacitated developer]],
+their [[#174|newly appointed]] master-in-training [[Zjing]]
+decided that they should work in separate shifts --
+Landhwa by day, Wangohan by night.
+
+"Finally," said Zjing on the videoconferencing monitor,
+"we cannot risk delays caused by arguments over coding
+style.  But neither do I wish to have two separate styles in
+one application.  Therefore, as Wangohan is new to this
+project, he will follow Landhwa's style as precisely as
+possible."
+
+Wangohan bowed his assent and took his leave to rest before
+the night's work.
+
+- - -
+
+When night fell, Wangohan began to familiarize himself with
+Landhwa's source code.  He was pleased to see that there
+were no magic literals, but pleasure turned to horror when
+he discovered that every constant in the application --
+regardless of purpose -- had been declared in a single,
+huge, uncommented /Constants.java/ file:
+
+|  ...
+   public static final String HELP = "HELP";
+   public static final String HELP2 = "Need help?";
+   public static final String HELPU = "/help";
+   public static final String HELPTA = "{{help}}";
+   public static final String HELPTB = "${help}";
+   public static final String HTTP = "HTTP";
+   public static final String HTTPU = "http://";
+   public static final String HTTPS = "https";
+   ...
+
+
+Wangohan was about to refactor the file when he remembered
+Zjing's decree.  Not wishing to disrespect the nascent
+authority of his longtime friend, Wangohan lifted his fingers
+from the keyboard and scowled at the monitor for a long
+time.
+
+- - -
+
+In the morning, Landhwa found a message waiting for him
+from Wangohan:
+
+    All has been coded according to your example.
+
+Landhwa pulled the latest changes from the repository and found
+that nearly every source file had disappeared.  Only two remained.
+The first Landhwa recognized; the second was but a few hours old:
+
+|   Constants.java            48K
+    Code.java               8090K

data/data/the-codeless-code/en-qi/case-179.txt

@@ -0,0 +1,34 @@
+Date: 2015-02-10
+Number: 179
+Title: Walking the Path
+Names: Bawan, Temple of the Burning Pool, Elephant's Footprint Clan
+Topics: third-party code, design, decisions, one-size-fits-all, reuse, management
+Geekiness: 1
+Illus.0.src: falling.jpg
+Illus.0.title: Curiously enough, the only thing that went through the mind of the rice bowl as it fell was "Oh no, not again..."
+
+Master [[Bawan]] was assisting the [[Elephant's Footprint Clan]]
+in creating a database service for the temple's audit logs.
+
+"We shall need at least three weeks to determine which NoSQL
+database engine would be best for this task," said Bawan
+to the abbot of that clan.
+
+"No need," said the abbot.  "The [[Temple of the Burning Pool]]
+has recently chosen a NoSQL engine for their own purposes.
+Follow the path they have taken.  We shall save much time."
+
+The master flung his bowl hard at the abbot's head.  The
+abbot ducked, and the bowl sailed harmlessly out the
+tower window.
+
+"See what your infamous temper has cost you, little master!"
+laughed the abbot.  "Now you have lost your bowl, and it is
+nearly time to line up for supper!"
+
+In one swift motion, Bawan flung the abbot out the window.
+Then he turned to the pair of astonished novices still in the room.
+
+"The abbot is following the path my bowl has taken,"
+explained the master.  "Come; perhaps he will save us a
+place in line."