codeless_code 0.1.2

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

@@ -0,0 +1,62 @@
+Date: 2015-11-16
+Title: Streams of Consciousness
+Number: 214
+Names: Kaimu, Banzen
+Topics: Java, languages, streams, annotations, lambda expressions, method references, simplicity, complexity, brevity
+Geekiness: 3
+Tagline: In which we long for a simpler life.
+
+Old master [[Banzen]] and young master [[Kaimu]] were
+sitting on a bench overlooking a gorge, watching fishermen
+in the creek far below.
+
+- - -
+
+Banzen said: "My apprentices learned of Java Streams this
+week.  Now they use Streams everywhere, even when a simple
+/for/ loop would be clearer..."
+
+     Kaimu mused: "When I first worked in the temple kitchens, I was
+     intrigued by the many blades in the knife blocks, and wished
+     to try them all.  But I did not know the difference between
+     a fillet-knife and a boning-knife, and ruined many good
+     fish."
+
+Banzen continued: "...I would happily teach them when to use
+Streams and when to avoid them, but I do not know myself.
+Nor have I read any simple wisdom on the subject..."
+
+     Kaimu continued: "In time I grew to understand the
+     purpose of each blade by observing how its shape and
+     thickness either helped or hindered my task.  In this
+     way I mastered not only the knives I used, but ones I
+     had never seen.  Error is a poor friend but an
+     excellent teacher."
+
+Banzen continued: "...Even if I could correct them today,
+tomorrow will only bring another peril.  Last month my clan
+began to play with annotations.  How can I conduct code
+reviews when essential functionality is migrating from the
+methods to the margins?  And now lambda expressions
+are springing up throughout the code base..."
+
+     Kaimu continued: "Each new cook brought his own
+     utensils, bright and sharp and strange.  My favorite by
+     far was a skinning-knife with a gut hook.  I hardly
+     ever needed it, but when I did it was exquisitely
+     suited to its task."
+
+Banzen continued: "...I do not understand why people
+must tinker with a simple language until it becomes so
+complex that it is nigh impossible to learn..."
+
+     Kaimu continued: "I still sneak into the kitchens from time to
+     time, to marvel at the latest tools by which complex tasks
+     are executed with a minimum of effort."
+
+Banzen leaned on his staff. "My only consolation is that
+every afternoon I can sit on this bench and contemplate the
+happy lives of those whose sole aspiration is to catch and
+clean fish."
+
+     Kaimu replied: "Indeed; theirs is a happy lot."

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

@@ -0,0 +1,41 @@
+Date: 2015-11-23
+Title: FAQ
+Number: 215
+Names: Qi, Laughing Monkey Clan
+Topics: documentation, brevity, FAQ
+Geekiness: 1
+Tagline: In which we fail to get a straight answer.
+
+A monk of the [[Laughing Monkey Clan]] created a useful
+and flexible toolkit which addressed a common business need.
+He demonstrated its virtues to the Temple masters, and soon
+was pleased to learn that the toolkit had been chosen as the
+recommended solution for all Temple applications.  Yet the
+monk soon discovered that popularity had its perils.
+
+"The situation is beyond frustrating," said the monk to his
+fellows.  "I included a dozen example programs, assembled a
+FAQ, created an introductory slide presentation, authored a
+/lengthy/ online tutorial, /meticulously/ commented the
+source code, and ensured that the API documentation is
+visible to developers within their IDEs.  Why, then, am I
+pestered day and night with the most basic of questions?"
+
+The old scribe [[Qi]] overheard.  Later that day he appeared
+at the monk's quarters, his arms overflowing with books,
+loose papers, and scrolls of many sizes.  These he spilled out
+onto the monk's desk.
+
+"For many years I labored as a developer and had the same
+complaint as you," said the scribe, catching an errant
+scroll before it rolled onto the floor.  "Thus I bent my
+mind to discovering how to create the Perfect Document: a thing
+that would instantly guide my users to whatever answer was
+required.  To do this I assembled all available wisdom on
+the subject, which I now share with you."
+
+The monk looked at the pile littering his desk.  "I do not
+have time to sift through all this.  Can you not simply tell
+me what I most need to know?"
+
+"Excellent!" said the scribe.  "You're halfway done already."

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

@@ -0,0 +1,47 @@
+Date: 2015-11-30
+Title: Proxy
+Number: 216
+Names: Landhwa, Spider Clan
+Topics: FAQ, laziness
+Geekiness: 1
+Tagline: In which we are not bothered.
+
+[[#215|This same monk]] continued to assist users of the
+toolkit he had authored.  But after another unproductive
+week spent answering their questions he reached
+the end of his patience, and again complained to his fellows.
+
+"Perhaps [[Landhwa]] of the [[Spider Clan]] can advise you,"
+suggested one.  "His talent for avoiding tedious work is
+legendary throughout the Temple; for although there have
+been lazier monks than he, none have managed to keep their
+heads attached."
+
+So the monk messaged Landhwa, described his problem,
+and asked his advice.
+
+An hour later, the monk received a reply on his screen:
+
+<em>Of all the users of your toolkit,</em> it began, <em>who
+is the most stubbornly proud of his own intellect?  Who
+would rather take a hundred blows than admit one gap in
+their knowledge of any subject?</em>
+
+The monk thought for a moment, then typed,
+<em>Kew Niao, certainly.</em>
+
+<em>Very well,</em> came the reply. <em>Whenever you receive
+an unwanted question, say that you are indisposed at the
+moment, and have the sender consult Kew Niao.</em>
+
+The monk frowned. <em>I will still find that bothersome,</em> he typed.
+
+<em>In that case,</em> came the reply, <em>configure your
+account so that questions with particular keywords
+are quietly forwarded to Kew Niao, with neither party the
+wiser.</em>
+
+<em>Excellent!</em> typed the monk. <em>How is this done?</em>
+
+<em>Sadly, I must confess that I do not know,</em> came the reply.
+<em>But I am absolutely CERTAIN that LANDHWA knows.</em>

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

@@ -0,0 +1,98 @@
+Date: 2015-12-08
+Title: The Chimera's Egg
+Number: 217
+Names: Suku
+Topics: simplicity, single-responsibility principle
+Geekiness: 2
+Tagline: In which we have met the enemy.
+
+After seven straight days of bone-chilling rains, soggy
+rice cakes and dripping tents, master [[Suku]]'s three
+apprentices could no longer remember what it felt like to be
+dry or warm.  So one can scarcely imagine their joy when Suku
+negotiated lodgings at the house of a great livestock
+merchant. The merchant's fire pits were kept burning at all hours,
+his larder was stocked with roasted meat and game,
+and he had no objections to the four travellers
+staying through the winter if they desired.
+
+"My only fee," said the merchant, "is that you assess the
+hermitage that maintains my site.  Every feature I request
+takes longer than I expect, and the site is riddled with bugs."
+
+"First Apprentice!" said the master to the eldest of her
+three companions. "Investigate those monks."
+
+"Where is this hermitage?" asked the First Apprentice.
+
+The livestock merchant pointed out into the rain,
+to a cluster of buildings atop a distant hill.
+
+- - -
+
+Soaked from head to toe again, Suku's First Apprentice came
+at last to the hermitage.  He was welcomed by the head monk
+with a cup of hot wine and the WiFi password.
+
+"Here is one problem," sniffled the First Apprentice
+as he browsed their repository.
+"Your 'Find Animals' page is astonishingly complex.
+Depending on the inputs given, it might query for
+animals /available/ for purchase,
+animals the user has /already/ purchased,
+animals in the /wish-lists/ of the user's friends,
+and so on.
+In each case, the validations done, the tables queried,
+the columns returned, and the information displayed are completely different.
+The result is an incoherent mess."
+
+"Indeed," agreed the head monk. "The code has grown so
+convoluted that none of us will touch it sober, and so
+fragile that we dare not even add trailing whitespace to a comment.
+
+"Then why not implement several /simple/ screens,
+instead of one unfathomable one?" demanded the apprentice.
+
+"You will have to ask the interface designer," said the head monk.
+"For we were told to follow her mockups exactly."
+
+"Where may this designer be found?" asked the First Apprentice.
+
+The head monk pointed out into the rain,
+to a small hut atop a distant crag.
+
+- - -
+
+Sodden from head to toe once more, Suku's First Apprentice
+came to the interface designer's hut.  There he was given clean
+robes made from recycled conference tote bags, while his
+muddy clothing was washed and dyed a more trendy shade
+of crimson.
+
+"At first the 'Find Animals' page /was/ simple," said the
+designer. "It was used for exactly one type of search, with
+one type of result to display.  Yet whenever a need arose
+which involved searching for animals,
+I was ordered to shove the capability into the 'Find Animals' page."
+
+"Ordered by whom?" asked the First Apprentice,
+punctuating his question with a sneeze.
+
+The interface designer pointed out into the rain,
+to the distant valley where the merchant's house lay.
+
+- - -
+
+Sneezing violently and leaving a trail of crimson dye (which
+had not had adequate time to set), Suku's First Apprentice
+staggered through the gates of the merchant's house and
+collapsed in front of fire pit where his fellows were
+playing mājan with their host.
+
+Weakly, the First Apprentice asked the merchant if he had
+truly insisted that all searching for animals be done
+through exactly one screen.
+
+"Indeed," said the merchant with a proud nod.
+"I did so to make things easier on the developers.
+For obviously /one/ screen is simpler to implement than /several/."

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

@@ -0,0 +1,67 @@
+Date: 2016-01-02
+Title: The Terminal Retrospectives
+Subtitle: or, After the Deployment
+Number: 218
+Names: Yíwen
+Topics: nonsense
+Geekiness: 2
+Tagline: In which we explain why there are twenty-six vacancies.
+
+<i>As most of the Temple is away for the mid-winter
+holidays, there has been little news to report.  But since
+some of you have expressed interest in the doings of our
+peers in the exotic Far West, I recruited the nun [[Yíwen]]
+to prepare an edifying monograph on that subject.</i>
+
+<i>I asked her to describe the conditions under which a
+developer in those strange lands might be judged as
+unsatisfactory.  Sadly, I see that -- yet again -- she has
+answered my earnest request with amphigory.  My most solemn
+apologies. -- Qi.</i>
+
+- - -
+
+
+A is for Agnes whose App must be killed //
+B is for Boris who's Broken the build //
+C is for Caitlin who Comments out code //
+D is for Derrick whose Data won't load
+
+E is for Egbert who swallows Exceptions //
+F is for Fay who won't Follow directions //
+G is for Garth who can't Grasp the essentials //
+H is for Hal who Hardcoded credentials
+
+I is for Ives who Indenting disables //
+J is for Jacob who Joins twenty tables //
+K is for Kathryn whose Kludge was all wrong //
+L is for Leda whose Lines are too long
+
+M is for Max using Memory excessive //
+N is for Nan choosing Names inexpressive //
+O is for Otto, Objecting to rules //
+P is for Petra who didn't use Pools
+
+Q is for Quincy whose Queries look grim //
+R is for Rex who Refactors at whim //
+S is for Sidney, stores numbers in Strings //
+T is for Tilton, to Triggers he clings
+
+U is for Ulmer who hates Unit testing //
+V is for Vin and his Very deep nesting //
+W is for Wade who logs Warnings most dire //
+X is for Xander whose cache won't eXpire
+
+Y is for Yancy who Yells when he's chided, and //
+Z is for Zeb who by Zero divided.
+
+
+
+== Editor's note
+
+The text was inspired by Edward Gorey's
+<i>The Gashlycrumb Tinies (or, After the Outing).</i>
+
+I'm very pleased to be working with
+<a href="http://scamperingkaos.tumblr.com/">Scamperingkaos</a>
+on a fully-illustrated version of this poem.

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

@@ -0,0 +1,56 @@
+Date: 2016-01-10
+Title: Nothing Really Matters
+Number: 219
+Names: Wangohan
+Topics: Java, annotations, error handling, fail-fast, code reviews, transactions, frameworks
+Geekiness: 3
+Tagline: In which nothing is wrong.
+
+The Temple used a popular dependency-injection and
+transaction-management framework, yet always there were
+junior monks who needed to be schooled in its ways.  One
+such junior monk had been tasked with creating
+a Service interface and its implementation class.
+The senior monk [[Wangohan]] was reviewing his code.
+
+"You have placed a /@Transactional/ annotation on a
+private method!" snapped Wangohan.  "That will do nothing!
+The framework only looks for such annotations on the
+implementations of /public interface/ methods!"
+
+The junior monk replied calmly: "I observed no error."
+
+"Your class also has a non-transactional method call a
+transactional one /directly/!" continued Wangohan.  "That
+too will do nothing!  Transaction management is only
+performed by the implementation's /proxy/, not the
+implementation itself!"
+
+Again the junior monk replied calmly: "I observed no error."
+
+Wangohan went to see master [[Kaimu]] and told him what had
+transpired.  "How can I work with such an idiot?" asked
+Wangohan.  "He only believes there is an error if it leaps
+up and bites his eyeball."
+
+/"Null,"/ said Kaimu. "The junior monk is no idiot.  For
+what he said is true, and yet he means the opposite of what
+he said, which is also true.  So he is twice correct, and
+concisely so."
+
+"Then master Kaimu must be two times too clever for me,"
+replied Wangohan.  "For he clearly just said something, but
+what he said was nonsense, which is the opposite of saying
+something.  Therefore let me depart before I become
+so wise that I surpass the junior monk."
+
+Wangohan bowed mockingly and went out.
+
+Later that day, Kaimu found the junior monk and said to him,
+"There is a smoke alarm in Wangohan's quarters.  Disable it.
+Then tonight when he is sleeping, set his room on fire."
+
+"Surely Wangohan would find this objectionable,"
+said the junior monk.
+
+Kaimu replied calmly: "He will observe no error."

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

@@ -0,0 +1,63 @@
+Date: 2010-11-23
+Title: Safety
+Number: 22
+Geekiness: 2
+Names: Laughing Monkey Clan
+Topics: reuse, encapsulation
+
+A monk of the [[Laughing Monkey Clan]] was well acquainted with
+the software produced by the Charitable Temple of the
+Bristling Yak, and he wished to use one of their modules for
+his latest project.  But the clan's own code repository was
+under heavy guard, and the monk had to obtain the permission
+of the monastery's hierarchy to consume any third-party
+software.
+
+The head priest of his clan was willing to allow the module,
+but under one condition only: a wrapper class must first be
+produced by the priesthood.  All access to the module
+would be done through the wrapper.
+
+Said the priest, "This will ensure that you do not make use
+of features which are too complex for your abilities.  And
+there is an added benefit: if we ever deem the Bristling
+Yak's implementation to be inadequate, our priesthood will
+be able to substitute another module for the wrapper's back
+end, and no one using the wrapper will be inconvenienced by
+the change."
+
+The monk bowed and reported this exchange to the Java master.
+
+The Java master called upon the priest, and suggested that
+they ride together up into the mountains, there to meditate
+on the best way to construct this wrapper.
+
+"You drive," said the master.
+
+They seated themselves in the priest's car, whereupon the
+priest frowned.
+
+"The tuning dial for my radio appears to have been stolen,"
+said the priest.
+
+"That is good," said the Java master.  "Music would be a
+perilous distraction on the narrow roads."
+
+"Also, the knobs for the air conditioning," said the priest.
+
+"Excellent!" said the Java master.  "Chill air exacerbates
+rheumatism, and causes disease of the bowels."
+
+The priest turned the ignition key, and was answered by
+silence.  He left his seat to investigate.
+
+"Additionally," said the priest, "it appears that the hood
+has been welded shut."
+
+"Will your good fortunes never cease!" cried the Java
+master.  "Now it is certain that no one may damage the
+engine.  And should the color of the tires ever prove
+unsatisfying, I expect that they may be replaced with
+no discernable effect upon the smoothness of the ride."
+
+

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

@@ -0,0 +1,24 @@
+Date: 2016-01-18
+Title: The Two Hard Things
+Number: 220
+Names: Kaimu
+Topics: cache invalidation, naming
+Geekiness: 1
+Tagline: In which we get two for the price of one.
+Credits: The quote cited by the junior monk is by Phil Karlton.
+Illus.0.src: thesaurus.jpg
+Illus.0.title: Changing the name "cache invalidation" would require that we all unlearn the existing name for the concept -- which is a form of cache invalidation.
+
+A junior monk said to master [[Kaimu]]: One of the
+Patriarchs claimed that there are "only two hard things" in
+our craft.  What are these "two hard things"?
+
+Kaimu answered: You only need to remember that the first
+hard thing is called "cache invalidation".
+
+The junior monk asked: Does that mean that a /whole/ cache
+is made invalid, or just some of its elements?  And why call
+it "invalidation" when the only error is that the data is stale?
+Wouldn't "cache element expiration" be a better name?
+
+Kaimu answered: Now you know the second hard thing.

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

@@ -0,0 +1,66 @@
+Date: 2016-01-25
+Number: 221
+Title: Indigestion
+Part: 1
+Geekiness: 3
+Names: Banzen, Satou
+Topics: Java, HTTP, ETag, message digests, hash codes, collisions, assumptions
+Tagline: In which we are too trusting.
+Illus.0.src: chocolate.jpg
+Illus.0.title: If we took the bones out, it wouldn't be crunchy.
+
+Java master [[Banzen]] was reviewing the code of a web
+application when he came across a new HTTP filter authored
+by his apprentice [[Satou]].  The old master called her
+to his office.
+
+"You have begun including an 'ETag' header with each page
+you send," said Banzen to the nun.  "Explain, for I have
+not heard of this header."
+
+"The ETag is a hash of the page contents,"
+said Satou with pride, glad to know something her master did not.
+"I calculate it just before I return the requested page to the browser."
+
+"What is its purpose?" asked Banzen.
+
+"An efficiency hack," replied Satou.
+"If the browser asks for that same page later,
+it can include the last ETag with its request,
+effectively saying:
+/I still possess this content that you sent me earlier./
+If the server then determines that a new response would have the same ETag,
+it discards the response and answers only:
+/Nothing has changed."/
+
+"Ah," said Banzen, squinting at Satou's code.
+"I notice that you obtain your 'hash of the page contents'
+by loading them into a byte-array called /contents/
+and then invoking /contents.hashCode()/.
+Are you certain that this will be a good digest value?"
+
+Satou thought a moment.  "The /hashCode()/ method returns a
+four-byte int, so the chances of collision should be about
+four billion to one.  I believe these are acceptable odds."
+
+The Java master congratulated his apprentice on her reasoning
+and bade her wait a few minutes while he fetched a suitable reward.
+Banzen returned with a box of assorted chocolates.
+
+"Take one," he said.
+
+The chocolates were indistinguishable, but they were laid out in neat
+rows and columns with a legend on the lid of the box.  Satou found
+a square labeled /Cherry/ and popped the corresponding
+chocolate in her mouth.
+
+Her expression changed from delight to confusion to horror, but
+she was too late to stop herself from swallowing the confection.
+
+"That... wasn't cherry..." she said, her pale face growing much paler.
+
+"Of course not!" laughed Banzen.
+"‘Cherry’ is only the name of the /square/ it was in.
+The /contents/ of the chocolate are anyone's guess.  Here," he
+said, moving a different chocolate to the vacated square.
+"If you liked that, have another."

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

@@ -0,0 +1,54 @@
+Date: 2016-01-31
+Number: 222
+Title: Stand-In
+Geekiness: 2
+Names: Banzen, Satou
+Topics: Java, principle of least astonishment, POLA, message digests, hash codes
+Illus.0.title: She doesn't know what her punishment will be, but she's fairly certain that she will *not* be giving it "two thumbs up".
+Illus.0.src: thumbs-up.jpg
+
+After the nun [[Satou]] had [[#221|corrected her code,]]
+she returned to Java master [[Banzen]] and asked that he
+review it.
+
+"So," said Banzen, squinting at the latest revision.
+"You /now/ obtain your 'hash of the pages contents'
+by taking the byte-array that holds those contents
+and sending it into /Arrays.hashCode()/."
+
+"Will that not work?" asked Satou nervously.
+
+"It will function adequately in this circumstance," said
+Banzen.  "However, if your 'hash of the page contents' is meant
+to be a digest, then you should use a utility that
+/calculates/ a digest."
+
+"But if my code functions adequately, and makes use of what
+I have on hand, then what is the advantage of such a
+change?" asked Satou.
+
+The master glared.  "Stand in that corner, with your elbows
+at your sides and your thumbs up," said Banzen.
+"And remain quiet until you are enlightened!"
+
+Satou glumly stood in the corner as she was told.  The
+master typed something into his phone, then sat back in his
+chair and fell silent as well.
+
+Seconds later, a temple guard who had been standing watch
+for hours in the snow burst into Banzen's offices, his knife
+at the ready and his spectacles fogged from the sudden
+change in temperature.
+
+"Forgive my summons, old friend!" said the master "There is
+no emergency.  Please, make yourself comfortable and I will
+explain."
+
+The guard removed his fur cloak and draped it on Satou's head.
+When he heard her muffled cry he jumped backwards with a start,
+knife raised.
+
+"That is not your usual coat stand!" exclaimed the guard.
+
+"No," said Banzen,  "But it functions adequately,
+and makes use of what I had on hand."

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

@@ -0,0 +1,54 @@
+Date: 2016-02-15
+Number: 223
+Title: Hidden Costs
+Geekiness: 1
+Names: Banzen, Satou
+Topics: principle of least astonishment, POLA, efficiency, learning curve
+Illus.0.src: coat-stand.jpg
+Illus.0.title: You know, IKEA sells a pretty nice coat stand which doesn't require food or bathroom breaks.
+Tagline: In which the management assumes some responsibility for your loss.
+
+As punishment for
+[[#222|implementing an unusual solution to a problem]],
+the nun [[Satou]] had been ordered by master [[Banzen]]
+to pose motionless in the entryway of his office
+each day, pretending to be a coat stand.
+
+Each new visitor that entered would invariably look about
+with puzzlement and ask what should be done with their coat.
+The master would then point wordlessly to Satou.
+Eventually the visitor would comprehend.
+
+When one hundred visitors had come and gone, Banzen asked his
+apprentice whether she had served his guests well.
+
+Satou replied, "Not one coat lay crumpled on the floor,
+dampened a chair, or burdened its owner."
+
+Banzen shook his head and ordered the nun to continue
+her services.
+
+When another hundred visitors had come and gone, Banzen again
+asked his apprentice whether she had served his guests well.
+
+Satou replied, "I stole from each."
+
+Banzen raised an eyebrow and asked, "What did you steal?"
+
+"Alas!" cried Satou. "Now I have stolen from you as well!"
+
+Banzen smiled and released the nun from her duties.
+
+
+== Qi's commentary
+
+Until this tale makes sense, I have stolen from you as well. //
+Alas, I know no better way to keep you from a life of crime.
+
+
+== Qi's poem
+
+Satou built a clock that lost a minute a day. //
+She hung it where forty million monks could see. //
+The next day she was sentenced to beheading -- //
+The nun could not deny that she had stolen a life.