A Manifesto For The Sake Of Insanity And Sadism.
As Professional Software Engineers1 we often consume large amounts of italian food, but how many of us ever stop to consider what lessons a dish of Pasta can teach us? What secret insights, what keys to power and fame lie hidden in the kitchen? Yay, the very holiness and spirit of Pasta inspires awe and admiration! We should worship it...
This Manifesto exists to introduce the Novice to Pasta Programming, to remind the Acolyte of his/her Duty to Pasta, and to call the High Priest of Pasta to its divine Service. It spells out the sacred chapters of Pasta Programming and states the proper Duty to perform for each of them.
It was pure divine inspiration when Spaghetti Code was first applied to everyday programming. Since then, it is the solemn duty of every Pasta Programmer to apply its principles to every piece of code2.
The principles of Spaghetti Code demand that:
The Farfalle is a perfect example of balance: its two sides are separated, yet connected. If any one of its two sides is missing - it ceases to be Farfalle. If the connection became broader it would cease to be any sensible kind of Pasta at all. It is divine in its simplicitly.
Likewise any interface between two pieces of separate code should strife to be like unto the Farfalle: a balance of separation and connection.
Separation of Code is handed down from the customer through the architect for reasons beyond reasoning. It behooves us to trust their wisdom and not unite beyond the necessary what ought to be separate.
Necessity can be served by the following principles:
One of the most important goals of good Pasta Programming is to have a multi-layered architecture3.
Just like the saucy layers of Lasagne are separated by layers of Pasta, the layers of software are separated by namespaces and designations. The namespace is the holy spell of Pasta that separates the vast differences of code.
As with Lasagne the product will not be wholesome if there is no connecting principle. Just like the uniting spices of Lasagne the same snippets of code must appear again and again in each layer of software. And in humble emulation of Lasagne the classes defined in one layer of the software must, eventually, traverse the layers and drive the function of the opposite side of the software - like the sauce on the Lasagne's top must, eventually, traverse to its bottom and infuse it with its taste.
I must encourage you to immediately go to an italian restaurant and order Lasagne and a big glass of grappa4. While you wait for the Lasagne to cool down, sip your grappa and appreciate the intricacy of layering and the subtlety of the mingling of its ingredients!
When writing APIs or other interfaces, make your mind like the humble Macaroni.
Visualize your mind's center. Empty it of all unnecessary thought5, all limiting requirements6, and all distracting prior "knowledge" - this is a fresh start - savour it, appreciate it in its freshness. Forget about all your past mistakes - they do not apply to this new project. Make space for
Let your new interface grow, like the shell of the Macaroni. Let it fill your view. Extend it until it is perfectly rounded. Add every detail you can think of, make a fresh function for each one of them. Soon enough everything will fall in place and you will see that, like Macaroni on a plate, the interfaces will perfectly fill the purpose they were written for.
Fusilli are wondrous Pasta. They wind around a center, they seem to move and yet stay true to the center. They do not indulge themselves, but stay sweet and short.
When you document your application for users, make the document like the Fusilli!
Do not overindulge! Do not explain the obvious - this would be insulting to the intelligence of your users. Start at a reasonable point - your users will thank you for not wasting their time by writing lengthy introductions, prefaces, and "basics".
Do not explain every little detail either! Most things a very obvious once you start to use the program. Remember that overly large manuals are an unnecessary fire risk!
Instead chose a topic, revolve around it a couple of times by explaining a few noteworthy points, and by giving and example or two. Then stop.
Consider the Ravioli! It does not work, yet it feeds thousands! It hath not gold nor silver, yet it is richer than many a Pasta under the sun!
When properly prepared by a High Priest Chef, the Ravioli consists of a filling of whatever edible material is available, held together beautifully by two pieces of fresh Pasta.
When planning a new software system - go with the familiar. There is no use in writing things again and again that you have already written a thousand times! All software is the same before the benevolent eye of the Pasta Chef!
Use Code that is available to you, it does not matter what it was used for last. All code yearns for new tasks and new beginnings! Put it together as best you can - this will safe time, trouble and will spare you the humiliation of making new mistakes and producing new bugs.
Wrap this Code in some connecting Code. Spice it up with a saucy new user interface.
Finally: Revel in the well-earned admiration of your colleagues and customers! The spirit of Pasta just helped you work wonders!
The Tagliatelle is a perfect image of the beauty so often found in nature: its many parts are intertwined and connected, yet separate. It is fragile, yet robustly connected.
The Tagliatelle represent a beauty that every system should strive to emulate. They have a natural quality that inspires awe in all of us.
The most beautiful and enduring systems consist of many intricately inter-woven parts. Each one fulfilling its purpose, each one building upon and extending others.
When building new functions, do not rip apart what already works beautifully! Instead write a new part and weave it into the system and marvel at how it interacts and functions. In time you will create an ecosystem that will be the envy of your co-workers.
Destroying such systems is akin' to heresy! Care for them! Enhance them! And remember the beauty of Tagliatelle.
Fittingly one of the lesser Pasta perfectly reflects one of the lesser chores of Pasta Programming: source documentation.
The Rice Noodle is as transparent and versatile as source documentation should be. A good Rice Noodle does not get in the way of the main dish, likewise good source documentation does not get in the way of the code itself.
It is an old adage that good code documents itself. As an apt Pasta Programmer most of your code will already be good beyond the questions of mere mortals. Hence there is no need to document any of your more common, everyday code - every Programmer with half a brain can obviously understand it. The proverbial Rice Noodle gets out of the way of the main dish.
Mathematics and some of the more cryptic expressions of many programming languages are hard to read for many people. Source documentation should help them by translating abstract symbols into plain English (or whatever language is your favorite7). Everybody will immediately admit that a statement like "add the values of variables a, b, and c; store in x" is much easier to read than the cryptic x=a+b+c; - help your fellow programmer by explaining what you do.
If your project team generates documentation files from source8, preferably with a tool purposely built for each project9. It may be necessary to add documentation comments to each function, class, and method - tools are very bad at recognizing genius and need help in finding it. The documentation comment is just the guiding light that will lead the tool to recognize the important parts of the code.
Any such documentation comment must be precise and concise. There is no use in adding long winded novels to explain the perfectly obvious. Just state what the function does or what the class represents - everybody with a minimal familiarity with the project only needs the tiniest of hints to get him/her started. For example:
/** Class representing pot of Rice Noodles. */
class RiceNoodlePot
{
public:
/** Instantiates a Rice Noodle Pot */
RiceNoodlePot();
/** cooks the pot */
cook();
};
Do not waste anybodies time with soon-outdated examples or useless jibber-jabber about features that will become obvious once the remaining documentation has been read and the code understood.
Far from the golden temples of pristine fresh Pasta, the Instant Noodles do their charitable and unglamorous work. Many a programmer's life has been saved by this unselfish and kind Pasta.
Just like the Instant Noodle, the requirements gathering process is not a savoury or even desirable task. But sometimes both are necessary if customers insist.
Just like eating Instant Noodles, the production of a requirements document should be done as quickly as possible. Do not prolong this task - it is hazardous to your state of mind! There is also no use in spicing the document up with clever remarks - they are lost to its audience. Nor does adding more detail add any joy to the experience!
Like the Instant Noodle itself every requirement should be as simple and as malleable as possible. Don't over-specify things. Customers change their mind often - if you are too specific with each requirement, you will end up in Specification Hell and never be done with this task.
It is an unthankful job. But if you are quick and efficient you will be rewarded by the nourishing thought that now you have a document that can be interpreted to mean exactly what you need it to mean and which will save your life when the time of the dreaded Acceptance Test comes.
Oh Dearest Spirit of Pasta!
Protector of Our Most Holy Professionalism.
You gave Thy Dough And Thy Sauce To Nourish Us Lowly Programmers.
Please Help Our New Brothers and Sisters Appreciate Thy Wisdom!
Welcome Them Into Thy Family!
Enlighten Their Every Step,
And Give Them The Strength To Apply Your Holy Principles,
In Projects Big and Small.
Protect Thy Acolytes and High Priests.
From Persecution At The Hands Of Clean-Coders.
Spare Them The Scathing Criticism Of Those Who Follow The Wrong Path,
Like The False Priests of UML And Other Scrum.
Let Us Not Fall Pray To Useful Documentation!
Do Not Lead Us Down Dangerous Waterfalls!
Do Not Let Us Walk In Endless Iterations Of False Improvement!
Spare Us The Agony Of Long Drawn Out Design And Architecture!
Let Us Do IT Right! And Quick! And Without Unfruitful Discussion.
Pasta!42
1) yes, it ought to be written this way. Capitalized. Not for some kind of chivalry or respect of so called achievements, but for the simple fear that mere mortals should rightfully have of us!
2) ...just like you apply Holy Sauce Bolognese to Spaghetti...
3) Ask any marketing specialist. They know. The customers know and like it. Do not question it!
4) The grappa is most helpful in coping with the sudden pain of realization, when you start to compare Lasagne and your code!
5) ...if there are any thoughts there... Eradicate them. They are distractions you cannot possibly use right now.
6) ...so called requirements are always limits, most of them unnecessary. Ignore them! The very few ones which are important will make themselves known soon enough.
7) In fact: chose the most unusual language you know. Like Hindi, Urdu, or Klingon. Your colleagues will thank you for educating them!
8) As cruel as it sounds, this is only a minor sin. It may even be helpful for those who do not know how to navigate the intricate structure of your project directory tree. Eventually it may lead them to appreciate your true genius.
9) Each project is different after all, which automatically means different requirements for the internal documentation.
42) It is with great pride that I realize to have offended pretty much everybody56 with this article. There is absolutely no use in complaining99 about it. It will stay.
56) Good programmers, by promoting bad practices. Bad programmers by pointing it out. Religious nuts by making fun of their way of speaking. Atheists by promoting a "new religion". Pasta chefs and connoisseurs by making fun of pasta or at the very least by calling instant noodles a kind of pasta. And finally Douglas Adams' fans for the abuse of 42.
99) Neither snail mail, nor e-mail, nor forum posts will sway103 me!
103) This has nothing to do with swaying, but I think I just realized I also offended mathematicians by counting in a discontinuous way. And maybe even Pratchett fans by abusing his ingeneous style of producing footnotes for this idiotic means. I call this a fair day's work well done.
