Blog . Adam Bard

With Apologies to Mark Twain

Mark Twain is one of my favorite authors, and my favorite work of his is an essay entitled “Fenimore Cooper’s Literary Offenses,” (which you should read) wherein he details many linguistic and logical violations commited by the aforementioned in his Deerslayer works.

In it he details 18 rules of writing which, while also damn funny, are quite applicable to anyone writing anything, including code with some coaxing.  Thus, I give you:

Mark Twain’s 18 Rules for Writing Code

These 18 rules require:

1. That the program should accomplish something and arrive somewhere.

2. That each function in a program shall be a necessary part of it, and shall help to develop it.

3. They require that the functions in the program shall be functional, except in the case of abstract ones, and that the reader should always be able to tell the abstract ones from the others

4. They require that functions in the program, abstract or not, shall exhibit sufficient cause for being there.

5. They require that when the comments are left, the talk shall sound like human talk, and be talk such as human beings would be likely to talk in the given circumstances, and have a discoverable meaning, also a discoverable purpose, and a show of relevancy, and remain in the neighborhood of the subject at hand, and be interesting to the reader, and help out the program, and stop when the people cannot think of anything more to say.

6. They require that when the author describes the character of a function in the program, the behavior and output of that function shall justify said description.

7. They require that when a function reads like the work of an illustrated, gilt-edged, tree-calf, hand-tooled, seven- dollar Friendship’s Offering in the beginning of a class, it shall not read like that of a mechanical turk in the end of it.

8. They require that crass stupidities shall not be played upon the reader as “optimization.”

9. They require that the functions of a program shall confine themselves to possibilities and let miracles alone; or, if they venture a miracle, the author must so plausibly set it forth as to make it possible and reasonable.

10. They require that the author shall make the reader feel a deep understanding of the functions in his program and of their purpose.

11. They require that the functions in a program shall be so clearly defined that the reader can tell beforehand what each will do in a given emergency.

In addition, the author shall:

12. Do what he is proposing to do, not merely come near it.

13. Use the right method, not its second cousin

14. Eschew Surplusage

15. Not omit necessary details.

16. Avoid slovenliness of form.

17. Use good, and consistent, syntax.

18. Employ a simple and straightforward style.

To Sloan, Manufacturer of Automatic Bathroom Fixtures, Regarding an Overzealous Toilet

Dear Sirs,
I am writing to make public my dissatisfaction with the automatic flushing system present on the toilet in the handicap stall, in the third floor men’s washroom in the McPherson Library at the University of Victoria.

It is clear to me that the designer and/or installer of this particular system is a “stander,” by which I refer to his stance as he proceeds to employ the toilet paper.  While I respect and tolerate this practice, I must cry foul at his design’s apparent disregard for the substantial “sitter” population present in the public at large.

The expected behavior of a toilet is to flush when the user has completed his task and is on his way to exit the stall.  Additionaly, if such timing can not be obtained, the toilet must at least refrain from flushing while occupied. However, this rogue toilet flaunts both rules, for it is misconfigured in such a way as to trigger the flushing sequence upon the occupant leaning forward, a motion necessary to a sitter such as myself, as well as any person wishing to rest his elbows on his knees.  This occurred at least 5 times during my last visit.

This is simply uncalled for.  The fact that this toilet is designed for individuals whose movement is impaired, and consequently who may not be so agile as I, only makes the situation direr.

While I understand the impulse to err on the side of flushing, certainly a company with such a reputation for water-saving devices can see the benefit in a “lazy,” rather than “greedy,” flushing system.  A toilet that only flushes once after a period of conclusive non-occupancy lasting at least 10 seconds would, in my opinion as a consumer, be a more reasonable choice.  For situations in which the toilet has not flushed, it is a small thing for a human operator to push the button signifying a manual flush.

Additionally, in a final insult, the automatic sinks in said washroom steadfastly refuse to activate without a substantial debounce, and activate for a duration insufficient for proper washing.

I hope this letter will prompt you to revise your design.

Sincerely,
Adam Bard

P.S. Sloan the band is all right by me.

It’s not learning your first language.  It’s not learning your second and third languages either. It’s not learning Lisp,  Scheme, Ruby, Python, Erlang, Haskell, Perl.  It’s not knowing C back-to-front, upside down.  It has nothing to do with Java, script or regular, nor is it anything to do with Objective C, C++, C#, or D. It’s not even assembly language.

It’s not grokking recursion.  It’s not using functional languages.  It’s not understanding things like function currying, and other fancy tricks.

It’s not knowing the hardware down to the bits.  It’s not programming for embedded systems, or for giant mainframe clouds.  It’s not getting a Computer Science degree. It’s not working for Google, or Microsoft, or Sun, or IBM, or anyone.  It’s not working for yourself, either.  It’s not managing your time, nor is it managing others’ time.  It’s neither agile nor extreme.

The hardest thing in programming is that no matter who you are, and what you’re doing, most of the time someone else has done it, done it better, and then released it for the world to see and use.  Instead of re-inventing the wheel, your best course is to close emacs, and spend some of that time you were going to spend creating the world’s seven millionth web framework scheme reading documentation, and learn to live with it.

Although I never really got the hang of that currying business.