Pondering Code

Meditations on The Codeless Code (Unofficial)

[pondering-code]

The Codeless Code is a collection of musings on the art of software development written by Qi between 2010–2016.

This page is a fan-made space for meditation on these stories and subsequent discussion. In this way, wisdom is revealed.

Qi intended these stories solely for personal contemplation. Yours truly considers this a mistake and thus rejects Qi's wishes.

[pondering-code]

Case 23. Shape

Geekiness: not geeky

One morning a nun named Zjing was passing by a terminal, around which were clustered several learned brothers of the One Shoe Clan. On the screen a program listing was glowing softly amid the golden shafts of dawn. Zjing paused to glance at it.

"That is not right," said the nun, and continued walking.

This was reported to the abbess of One Shoe, who later that day found the nun working in the pottery shed. The nun's hands were red and wet with clay: she was turning a new water jug on the potter's wheel, for that was her assigned duty.

"A learned brother says that you showed him grave disrespect this morning," said the abbess. "Do you deny this?"

"Wú," said the nun. "A hornet may sting a bear, when the nest is underfoot."

"The brother maintains that he did not require correction," said the abbess. "I watched him execute this selfsame code, and found its performance to be quite satisfactory. He says that you tarried for no longer than it takes a branch to fall, and thus could not have judged his labors fairly."

"Wú," said the nun.

"Explain," said the abbess.

Zjing placed the newly-made jug on a shelf, next to a dozen others. All were perfectly symmetrical, and identical in every proportion.

The nun hesitated for a moment, then with a snarl squeezed the pliable throat of the new jug in both hands. She then punched its bowl repeatedly, and mangled its elegant handle.

Drawing a breath, Zjing filled a pitcher of water and emptied it into the lopsided jug. She stepped slowly backward to stand beside the abbess.

Every last drop of water was contained.

"Satisfactory," said the nun.

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

Many argue that consistency and rigor are vital, in clay and code alike.

A program may complete, and yet be a complete disaster. This becomes apparent over months and years of extending its features.

With experience, one can foresee such mistakes, but it is often difficult to introspect and justify this type of intuition beyond appeals to aesthetics. Like all engineering, software is an art as much as it is a science.

[pondering-code]

Case 22. Safety

Geekiness: moderately geeky

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 discernible effect upon the smoothness of the ride."

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

What is the purpose of welding shut your own hood? What is the purpose of restricting API access for your own team? Unless there is a technical reason, such as avoiding language features to stay compatible with different compilers or runtimes, what is the benefit of such safeguarding?

What terrible mistrust. Passive-aggressive.

This type of conservative programming is alien to me, and I can only guess that not everyone is so lucky.

[pondering-code]

Case 21. Interrupt

Geekiness: moderately geeky

A certain monk was reported to be unwilling to leave his terminal. For two days he had gone without food or sleep.

When the Java master investigated, he found the monk visibly shaken. On screen was the following code, which at that moment was running under the debugger:

while (true) { /* do nothing */ }

"I have asserted that the loop must execute while truth itself is true," said the monk. "Yet if I hit the Interrupt key, the loop will terminate. The implication is that, in that precise moment, truth will no longer be true. How can any of us dare to disturb the program? We might bring chaos upon the world!"

The Java master reached down and pulled the plug out of the wall. The screen went black.

"Now the loop can never be interrupted," said the master.

The monk's mind was eased.

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

This one is soothing for the soul.

I can't see much of a lesson. Koans are not lessons though. And these are not koans.

[pondering-code]

Case 20. Neither Yes Nor No

Geekiness: moderately geeky

A nun of the Elephant's Footprint Clan sat cross-legged upon her desk, quietly contemplating an Entity-Relationship diagram on her whiteboard.

The Java master[*] observed this and approached.

The God of the Silence Between Words was already in the room.

———

The nun pointed to the diagram. "This column named complete is declared to hold an integer. An examination of the data shows that it contains two unique values: zero and one. I presume that the zero indicates falsehood, and the one, truth."

Said the master: "Only an initiate can say what is counted by these numbers."

Said the God of the Silence Between Words: "The presence of a single zero implies the existence of a one to count it, and then a two to count both, and likewise to infinity. Did the universe spring thusly from the shell of a serpent's egg?"

———

The nun raised the first two fingers on her right hand. "I have considered storing a two in some random row, merely to observe the effect on the application."

Said the master: "You seek to determine whether truth is regarded as the presence of a one, or the absence of a zero."

Said the God of the Silence Between Words: "The absence of a zero implies a presence. The presence of a zero implies an absence. When the serpent devours its tail up to the tip of its tongue, then what remains?"

---

The nun pressed her index finger to her chin. "The column also allows nulls. If the column asks a question, convention dictates that a null represents an unknown answer."

Said the master: "This null is either the shrewd pause that precedes a lie, or the gentle hush before the revelation of truth. Its quality rests entirely in what it will become. Only when it ceases to exist may we understand what it was."

Said the God of the Silence Between Words: "The ghost borrows the form of the departed. Yet what shape may we assign the spirit of the yet-unborn?"

———

The nun steepled her fingers. "Before the application queries the database, the value of this column is unknown. Afterwards, any null in this column will be represented intentionally as a null Boolean. The value is then simultaneously known and unknown."

Said the master: "We have learned only that we have learned nothing, yet this is the root of wisdom."

Said the God of the Silence Between Words: "The sage and the fool go to their graves alike in this respect: both believe the sage to be a fool. Where, then, may wisdom be found?"

———

The nun folded her hands in her lap. "The null SQL integer, persisted, becomes the null Boolean in fleeting memory. Two nothings, of wholly different natures. How can absences be inequal?"

The master nodded.

The God of the Silence Between Words raised an eyebrow.

[*] Probably Kaimu.

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

So much deliberation, and for what? Just to grasp a simple boolean.

Does 1 mean completed? Is it okay to pass 2 instead of 1? Is it okay to pass null instead of 0? Are there guards against these cases?

A whole meeting could've been spared, had the developer used a boolean or documented intended values explicitly.

[pondering-code]

Case 19. By Any Other Name

Geekiness: moderately geeky

The old scribe was asked why, in his official accounts, the temples and the clans were named but the many monks and priests were not.

"If I gave you a sheet of figures to tally, would you first bestow a name upon each number seven?" asked the scribe, dismissing the questioner with a wave of an ink-stained hand.

This was mentioned to the Java master, who nodded and finished his tea.

The next morning the scribe ascended to his office, only to find the following written in thick block letters above the door:

public static final int NUM_DAYS_IN_WEEK =

At this, the old scribe Qi was enlightened.

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

A simple lesson about naming constants according to semantics. It makes the use cases easier to read.

Suppose temples and clans mean classes and methods, which are named while literal constants were not.

[pondering-code]

Case 18. Necessary Features

Geekiness: slightly geeky

This same monk of the Elephant's Footprint was poring over the code created by his clan. There were several competing implementations of a particular Data Access Object; at present he was attempting to decide which would become the definitive one that his clan would adopt.

"Each implementation has its own particular virtues and vexations," said the monk to the Java master. "And each has features the others lack. I must consign all but one to the winds of oblivion. How am I to choose?"

"I cannot answer when I am thirsty," said the master. "In the cabinet beside you are three wooden cups. Fill one from the river, the second from the temple well, and the third from the water-seller in the village. Bring all back to me without a drop spilled, and I will offer you what help I can."

The monk did this, and set all three vessels before the master.

"What have you learned?" asked the master.

The monk bowed. "If you give a coin to the water-seller in the village, he will strike a gong twice: once before filling your cup, and again when you have had your first sip. If you fill your cup from the temple well, no gong sounds but the bucket is heavy. If you dip your cup in the river, the fish are troubled and the river-god must be appeased by a gift of ten white stones."

"I can drink but one of these," said the master. "Which will I find the most pleasing?"

The monk considered carefully. "The river was cold, but not altogether clear. The temple well I have drunk from in the past: its waters are bitter with limestone. And though I am not acquainted with the water-seller, I heard his gong many times today. On this evidence, I would choose the cup from the water-seller."

"A most sensible conclusion," said the master. "Indeed, I have visited this same water-seller every morning for eight years, and found the experience perfectly satisfying each time. Which is the vessel that he filled?"

The master sipped from the indicated cup, and his face fell in disappointment. "Young brother," he said. "You have completely misunderstood my thirst. Where is the sound of the gong?"

———

The master's thirst is unsatisfied yet the monk has his answer— what sound was the vessel that poured it?

The monk would have fared better if he had set a brass censer on the window-ledge and merely waited for rain.

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

The master wants not only to drink, but to hear the gong. Sometimes the requirements are not obvious. So it is in software.

Study people's use cases carefully when implementing breaking changes.

[pondering-code]

Case 17. Not Invented By Me

Geekiness: slightly geeky

A monk of the Elephant's Footprint Clan had been charged with eliminating the reams of redundant code created by that clan. He approached the clan's head priest for guidance.

"Here, for example, are five schemes for managing user preferences," said the monk, spreading the printouts on the table. "I must either pick the superior one or implement some compromise. Either way at least four modules will be tossed into the fire, and their authors ordered to consume the code of a rival."

"Then you are doomed," said the priest. "Once the cat wets her paw to rake a carp from the pool, she will not trade the belly for ten thousand mice."

The monk wiped a hand across his brow. "And this is but one of a dozen redundant subsystems I must consolidate! Today I saw one of the senior brothers sharpening his throwing-knives. Is there no way that the monks of our clan might be mollified?"

The priest held up his left hand, which was missing the smallest finger. "If the cat cannot have the carp, a bit of the carp-thief will suffice."

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

Once a developer picks a solution, she is set on writing that solution - and persuading her otherwise will be costly.

But the nature of the cost reads ambiguously: does a bit of the carp-thief mean voicing frustration at the team lead, or that each developer should have a say and contribute to the new solution to truly adopt it amicably (i.e. "eat" a bit of the carp-thief solution instead of "eating" their own carp)? Both thoughts contain a lesson.

[pondering-code]

Case 16. Documentation

Geekiness: not geeky

An abbot of the Seven-Clawed Blind Eagle Clan was tallying the deliverables of the temple monks, when he noticed that a monk of the Laughing Monkey Clan had produced no design documents.

"What if a problem were discovered in our production system?" the abbot asked the monk. "How would the cause be understood by any besides yourself?"

"The code itself should be examined," said the monk. "The Document is a sickly beast, easily subject to the Three Plagues of Error: omission, obfuscation, and obsolescence."

The abbot reported this to the Java master, who said: "Have the monk balance on one foot with his staff outstretched, every day from dusk to midnight. If he can say a word to please me I will revoke the punishment, but not otherwise."

"Is there such a word?" asked the abbot.

"It is difficult to be certain," reflected the master. "Yesterday I was pleased by the sound of a cricket chirping after the first three drops of rain. The day before, the plashing of milk in a pail returned me to a pleasant memory of my youth. Perhaps the answer lies in the fragrance of a white lotus that drifted once in the pond below my window."

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

The master's favorite sound changes daily, but that doesn't mean there's no point in documenting it. Since it's not documented, the monk will have no way of knowing the right sound without intimate knowledge of his master's life.

Similarly, in programming, project design may change over time, yet a degree of documentation is useful for reference and onboarding.

It's a pain and it can become outdated, but it's still worth it. You don't have to go overboard with it, a brief outline of the structure and reasoning may suffice.

[pondering-code]

Case 15. Immutable

Geekiness: extremely geeky

A novice was recently arrived from the Temple of Three Stones where only C was used. He was new to the ways of Java, and soon stumbled upon the immutability of Strings.

"I wish only to convert the contents of this field to mixed case!" he cried. "Yet this requires the construction of a StringBuffer and a new String subsequently, with many untouched characters copied twice between them! For what purpose were Strings designed thus?"

A learned sister heard, and advised him: "The brass coin passed from hand to hand may still be exchanged on the morrow; not so the egg." The novice was enlightened.

Soon the novice was defining all his classes to be immutable. Not one property could be modified: a new instance had to be created with the necessary changes. His constructors were sometimes astonishingly large and complex.

The Java master was told of this, and said: "Let the form of an egg be cast in brass, and given to the nun to breakfast upon."

In this manner was the nun charged with correcting the novice.

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

Immutable data structures have their place, yet they are not suitable for every task.

Just like the brass coin, they may get passed around with the confidence of still holding the same value. But, as an example, sorting a list often happens in-place, thus a mutable list is required. Just like brass won't do for breakfast, an immutable list will not do for sorting.

[pondering-code]

Case 14. Hello, World

Geekiness: slightly geeky

On their first day in the temple, the Java master posed the following three questions to the novices:

"Oftimes, when we acquire a new language or library, the first program we write is Hello, World. Its purpose is to inscribe these words in some fashion that will demonstrate the expected behavior of the technology. After this is done, the program is never run again.

"Now: why does it say hello, and not also goodbye?

"And: why say hello to the world, when the audience is but a single soul who will discard it after its first cry is uttered?

"And: why should it utter a greeting, which will never be answered in kind?"

———

Speak me a word which means hello and goodbye— is it not the first cry of an infant?

Find me a pinnacle from which the world may be seen— in whose eye, then, is reflected every tiger, and the desert of endless sand?

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

Hello, World is the first cry of an infant project. It will grow, and in time be answered by its users. It's not yet time to say goodbye.

Also, personally, I've always thought of it as me saying hello to the world through the program.

But what lesson the master intended here beyond that, escapes me. Maybe that is it, maybe a simple reminder of our humble beginnings.

[pondering-code]

Case 13. Evolution

Geekiness: not geeky

A novice studied the Java master's* code and adopted the master's style to an exacting degree: the design patterns employed, the naming conventions for variables, the number of spaces used to indent each nested block. Even the comments were written in an impressive imitation of the master's own voice.

During his next code review, the novice was surprised to find the Java master tremendously displeased.

"But, master," protested the student. "I have followed your example down to the final semicolon. See, here is a utility class you wrote only last month: is it not as like to my own code as two eggs from the same clutch?"

"And therein lies the problem," scowled the master. "Yesterday I was a fool, the week before an idiot, and last month an imbecile. Don't show me code I might have written yesterday. Show me code as I will write it tomorrow."

* Probably Banzen.

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

Learn the method, not the instance of it. Oppose book worship.

[pondering-code]

Case 12. Effect

Geekiness: slightly geeky

Three young monks—one from the Spider Clan, one from Laughing Monkey, and one from Elephant's Footprint—had been arguing about which was the more important: webtier code, business tier, or persistence. Finally they agreed to pose the question to the Java master.

The master called in one of the burly gardeners who maintained the temple grounds, and instructed him thus: "Beat and kick these three monks soundly for one minute. Afterward, you may continue to beat and kick them for as long as you desire."

The gardener thrashed the monks for a full seven minutes, then bowed and left.

"Now," said the master. "Who bears the greatest blame for your bruises today? Myself, for summoning the gardener; the gardener, for the six minutes left to his discretion; or the gardener's hands and feet? Consider your answer, or I shall call him in again."

At length, the monk of the Spider Clan said, "The carpenter who raised the first beam of this temple bears a greater blame."

The master was satisfied.

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

In the master's analogy, instead of importance of project parts, we have blame for bruises. The conclusion is that there is no meaningful "most important" part of the project, as they can only exist together. The closest person to deserve credit, is whoever started all of it.

Team projects are more collaboration than competition.

[pondering-code]

Case 11. Cages

Geekiness: moderately geeky

To prevent any further proliferation of redundant code, the abbot of the Elephant's Footprint Clan decreed that his monks were only to produce code which was application-specific. Anything of a more general nature had to be proposed to a Software Reuse Subcommittee, which researched open source solutions, weighed the merits of the proposal against the needs of the various applications, amended the design as its members saw fit, and (if all signs were favorable) put the project on the implementation schedule. The whole process, from inception to execution, took many weeks.

When news of this policy reached him, the Java master sent for the abbot's two prized songbirds. His letter promised that the birds would be returned the following week. And so they were, in two separate bamboo cages of the Java master's devising.

The bars of the first cage were a handspan apart; the bird had easily escaped during the journey.

The bars of the second cage were so close that neither light nor air could pass through. The bird inside was dead upon arrival.

Tied to each cage was a poem in the master's hand:

Along the road from air to coffin lie the many houses of cage.

The house of the thrush is not shared by the worm and the bull.

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

This is the opposite of the previous koan, Pride. No need to rush to the other extreme, avoiding duplication to the point of spending weeks looking for existing solutions.

Along the road from 0% to 100%, there lie sensible levels of duplication, or whatever other quality concerns you. When building a cage, you don't have to pick 0% bars (air) or 100% bars (coffin).

Pick the right level for the job. Some tasks call for more strictness than others. Some tasks are small as a worm, some are large as a bull. There can be no universal set of standards for all of them.

[pondering-code]

Case 10. Pride

Geekiness: slightly geeky

After a cursory inspection, the Java master decreed that each monk in the Elephant's Footprint Clan would henceforth catch his own fish, harvest his own rice, sew his own robes, and cobble his own shoes.

Within a month, the monks were half-naked and severely malnourished. Deadlines began to slip. The abbot implored the Java master to reconsider his decision.

"Very well," said the Java master. "Every Thursday, have them also burn their robes and shoes, and cast their rice and fish into the river."

The abbot asked what transgression his clan had committed to merit such punishment.

"Punishment?" said the Java master. "I intended only to reward. Do not the monks of the Elephant"s Footprint relish their independence and self-sufficiency? Their code tells me as much:

"Each has authored essentially the same Data Access Objects and Value Objects as his neighbors. Each has crafted his own String utilities and configuration file parsers. Each has taken exquisite pains to design, implement, integrate, test, debug, repair, and extend that which he might merely have consumed from one of his brethren.

"Shall I infer incompetence? If so, then every last monk of the Elephant's Footprint must be cast out of the monastery.

"Shall I infer willful ignorance? If so, tradition demands that they blind themselves with nettles, and then be cast out.

"Shall I infer contempt for the preciousness of time? If so, the dungeons await...

"But no," concluded the Java master. "I shall instead infer pride—pride taken by each that his code is superior to that of his brethren. Pride is one of the Four Seeds of Greatness, and must be encouraged. Let the Elephant's Footprint hone its skills with shears and spears, with needles and sickles, until every monk may be likewise proud of his fine robes and the bounty on his plate!"

"There will be little time left for coding," observed the abbot. "And the Emperor is quite literal in his interpretation of the word deadline."

The master nodded. "The merchant, lately ruined, knows only the pangs of loss. Whereas the old hermit extols the virtues of austerity, and will not change his state. Yet are these not the same man, separated only by a gulf of years?"

Thus was the Elephant's Footprint spared twice and corrected.

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

See: Not-Invented-Here Syndrome. A reluctance to adopt solutions from others due to: being territorial; pride; fear of dependency and loss of control. Common in tech.

[pondering-code]

Case 9. Infinities

Geekiness: slightly geeky

Two monks of the Spider Clan were arguing whether the new input validation routine was caught in an infinite loop.

"How long has it been running?" asked the abbot.

"No more than thirty minutes," said the pale thin monk.

"Yet no less than that either," said the dark fat monk.

"And you have done nothing this whole time but wait for it to complete?" asked the abbot.

The monks bowed their heads in shame.

The abbot reported this to the Java master, who nodded. "Which of them believes that the loop is not infinite?"

"The pale thin one," said the abbot.

"Then give him a skin of wine, for he is wise. No loop may be truly infinite. Someday the power will fail, the server will rust, the temple will crumble, and the sun will swallow the earth."

Asked the abbot, "What of the dark fat one, who believes that the loop is infinite?"

"Give him two skins of wine, for he is wiser. To the user waiting at his browser, ten seconds is agony, a minute is an aeon, and anything longer is effectively an eternity. When the tiger mauls the antelope, the antelope does not question whether eight claws were used, or a million."

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

Don't wait for thirty minutes just to see what the answer is. You can often cut corners, like Google only showing an approximate number of search results.

See also: optimistic UI. Show expected click results (like updating text, deleting items) before the server confirming them.

[pondering-code]

Case 8. Reduce, Reuse, Recycle

Geekiness: not geeky

A novice asked the great master: "What is the Way?"

The master replied, "Writing code is the Way."

The novice then asked, "What is not the Way?"

The master replied, "Writing code is not the Way."

The novice said, "Then the writing of code is all things."

The master replied, "And the not-writing of code also."

The novice asked, "At the present moment, are we writing code, or not writing code?"

The master replied, "We are the code."

⋅⋅⋅⋅⋅⋅⋅⋅⋅ My reading ⋅⋅⋅⋅⋅⋅⋅⋅⋅

Both writing code and not writing code is the way. Both are parts of development. Often, reusing and rewriting is better than piling on more code. "One of my most productive days was throwing away 1000 lines of code." — Ken Thompson

Just as writing and not writing are parts of one process, so are the coder and the code. You are writing the code for humans, therefore, make it easy to maintain.

Consider both the coder and the code, both writing and not writing. This is the way.