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.