Beefy Boxes and Bandwidth Generously Provided by pair Networks
Think about Loose Coupling
 
PerlMonks  

Re^3: improving the aesthetics of perl code

by Ytrew (Pilgrim)
on Jan 22, 2005 at 22:33 UTC ( [id://424288]=note: print w/replies, xml ) Need Help??


in reply to Re^2: improving the aesthetics of perl code
in thread improving the aesthetics of perl code

The fat cat sat on the mat. The fat cat was tired. The fat cat had just eaten. The fat cat ate a lot. That made the fat cat sleepy. The fat cat went to sleep on the mat.

It is far better to write the simplistic text above than the purportedly "more adult" text below, in my opinion.

"The aforementioned creature, grown senecent in the ways of corpulence, had taken up residence upon an entanglement of fibrous matter. Bestirring itself to the siren call of the Sandman's lair, it gravitated in a state of satiety, brought on by an act of pedestrian consumption, noteable only by it's excess. Led thereby to the banquet of Morpheus, it took up the preoffered cup, paused, and drank deeply."

The second paragraph is similar to a lot of code I see in the world today: it suffers from trying too hard. It has several faults. It's excessively wordy. It uses too many confusing metaphors. For example, "Morpheus's banquet" refers to sleeping, not eating.(Morpheus was the ancient greek God of Dreams.)

It contains both grammar mistakes ("it's" rather than "its") and spelling errors ("preoffered" is particularly confusing, as it looks like "pre-offered" rather than "proffered").

It also fails to mention that the creature in question is really a cat. Given that the story is about the cat, it's a major flaw.

Suppose I hire a 14 year old kid as a junior editor. If I tell him "change the cat from fat to thin", and "make him drink, not eat", I know he can fix the first story with ease. I also know that he'll have a harder time with the second story: it will cost me more money, because he'll get confused, and take longer trying to figure it out. It would take a lot of editing to fix the second story.

If I were to edit the original text, I would find that there's not as much wrong with it. The word "fat" is repeated needlessly. The paragraph doesn't stand alone: it assumes that a specific cat has been previously identified, by the use of the word "the" rather than "a" when refering to the cat. The notions of sleep and causation are repeated.

I would probably write the story as:

"Once upon a time, there was a fat cat. The cat sat on a mat. It was sleepy, because it had just eaten a lot. So, it went to sleep on the mat."

Note that it's still readable by a grade school student, or by a non-native English speaker. I've taken seven years of French in school, and I still stumble when trying to read children's books. I imagine non-native programmers feel similarly with English.

Remember, the purpose of programming is not creative expression, but rather clear exposition. The CPU needs to know what to do: the maintainer needs to know why you did it. No one needs to know that you passed grade 13 English with a 97% average (except maybe your university English professor).
--
Ytrew

Replies are listed 'Best First'.
Re^4: improving the aesthetics of perl code
by Anonymous Monk on Jan 23, 2005 at 00:42 UTC

    The overweight cat was feeling drowsy having eaten a large meal, and lay down on the mat to sleep.

    Concise, joined up, complete.

    Software constitutes some of the most complex creations of man. Writing software is one of the most challenging endevours man undertakes, and requires education, skills and experience to do well.

    You would not employ a lawnmower service apprentice to work on your Lexus or Mercedes. Or a flight attendant to fly your 767. Nor a med. student to perform open heart surgery. Why would you employ a 14 y/o to edit anything important?

    Equally, employing unskilled, or semi-skilled persons to maintain your business software, and deskilling your programmers to write baby code in order that you can, is stupid and counter productive.

    If you dumb down the code, the maintenance programmer will never aquire better skills. Supervise their work and train them. The rewards will outweight the costs.

    "No one needs to know that you passed grade 13 English with a 97% average"

    Then why is your highest priority item?

    "As others have mentioned, spelling and grammer are very important. Learn to express yourself in English, first."

      The overweight cat was feeling drowsy having eaten a large meal, and lay down on the mat to sleep.

      Concise, joined up, complete.

      And yet, your re-factoring of this very simple story contains several subtle flaws. First of all, "overweight" generally implies someone who is thinner than someone who is "fat". Someone who is "drowsy" is just on the threshold of becoming "sleepy". In the original story, the cat sits on the mat: it doesn't lie on it. In the refactored version, the meal is correlated with sleepiness: in the original, direct causation is explictly spelled out.

      If some zoologist spent months coming to the conclusion of causation, it's a serious loss of domain knowledge to downgrade the information back to mere correlation. Similary, if overweight cats sit rather than lie, it may imply something important to future zoological researchers. As you point out, it can be tricky to manage code: the K.I.S.S. principle of engineering should apply wherever possible.

      Software constitutes some of the most complex creations of man. Writing software is one of the most challenging endevours man undertakes,

      I disagree. There are several domains far more rich and complex than computer programming, and yet we manage complexity in them on a regular basis. Physics is nothing less than the formal study of the entire physical universe. Modern medicine is the study of how to maintain over six billion uniquely distinct lifeforms in working order, each one of which is a composite of a myriad different kinds of sub-lifeforms, and miniature ecosystems. Computer Science is the formal study of algorithms, including both their design, and formal proofs of correctness. It's only a tiny subset of the vast, mind-boggling complexity of mathematics. Non-commutative algebra is complex. Quantum mechanics is complex. Computer Science is complex. Computer programming, especially as applied to typical business purposes, is not so complex.

      Programming is largely just a matter of encoding: translating known algorithms into existing computer languages to solve real world business problems.

      and requires education, skills and experience to do well.

      This is true of almost any discipline, from basketweaving to automotive repair. It's a bad idea to trivialize any form of learning.

      You would not employ a lawnmower service apprentice to work on your Lexus or Mercedes.

      I most certainly would. If a "lawnmower service apprentice" (or any other unskilled person, for that matter) can't re-fuel the vehicle, check the oil, top up the fluids, or change a tire, then the car design is too complex.

      If a "semi-skilled" automobile mechanic can't repair the car, the design is also flawed. Remember, mechanics are maintenance workers: they're not all formally trained automotive design engineers. They don't need to be. I doubt either my cousin or my uncle could calculate the stopping distance of my car based upon the co-efficient of friction of the brake pads and the related engineering equations: but they certainly know how and when to replace them. That's because automotive design engineers deliberately take maintenance into account: they make parts easy to replace, they provide "dumbed down" (i.e. "useful") replacement part and part substitution tables, and they document everything at a level the mechanics can understand. They specifically don't assume they're writing for someone with an engineering background.

      Or a flight attendant to fly your 767. Modern airplanes are so well engineered that they almost fly themselves. A flight attendant with minimal training (or more likely, minimal coaching from the control tower), could active the automatic landing systems in an emergency. That's because the systems are well designed, and simple.

      Pilots hate complexity. The main goal of running an airline is to force the pilot to think as little as possible. I know, because I worked for the airline industry for 2.5 years, providing data for the pilots to take off and land. The goal was always to make everything as consistant and obvious as possible, because every time a pilot has to make a decision, there's a small chance he'll make the wrong decision. If he doesn't have to plan, he can focus all his attention on making his execution perfect.

      Nor a med. student to perform open heart surgery.

      Nurses, not doctors, take blood pressure, throat swabs, and perform other mundane operations. My family doctor doesn't have the skills of a heart surgeon, but he's certainly not useless. In medicine, again, a tiered approach manages complexity in a cost effective way. If everyone in the hospital absolutely had to be a surgeon, because "medicine is complicated", then we could only afford one or two hospitals per country. There would be surgeons sweeping the floors. It would be a pointless waste of talent.

      Why would you employ a 14 y/o to edit anything important? Why not? If the work is within their level of competency, then it's cost effective to hire them, since they tend to work for lower wages. Sound business practices dictate that I should hire the person who will do the required job, for the lowest wages. I don't care how smart my janitor is; I just need clean bathrooms.

      Equally, employing unskilled, or semi-skilled persons to maintain your business software, and deskilling your programmers to write baby code in order that you can, is stupid and counter productive.

      I disagree completely. I've shown that there are tiers of competency throughout the rest of industry, for reasons for cost-effectiveness, and maximizing the productivity of the true experts. I see no reason why programming should be different, here.

      After all, aren't all computer programmers in some sense just "semi-skilled" computer engineers: unaware of all the electronic complexities of the circuitry and hardware that they operate? Call it "dumbing down" if you like, but the more common term is "abstraction", and it lies at the heart of how we manage complexity, both within and outside our field.

      The term "baby code" is just plain perjorative: all code must still meet its full business requirements, or it's useless. Code that fills the required business need, and is easy to maintain is correct code. Anything else is not.

      It's not "de-skilling" a programmer to teach him to express himself clearly. After all, programming is almost entirely about clear, unambiguous specification of requirements: both to the machine, so that work is carried out correctly, and to fellow programmers, so that the specifications are obvious and easy to modify.

      If you dumb down the code, the maintenance programmer will never aquire better skills.

      I disagree. Training programs for staff should not be carried out on mission critical systems.

      Supervise their work and train them. If I have to pay a senior programmer to supervise each line of code a junior programmer writes, it's equivalent to paying the senior programmer to write it for me. The senior programmer is still doing the real work: the maintenance programmer is being trained for free on company time. Mentoring may be one useful form of training, but it's certainly not the only kind, nor is it guaranteed to be the most effective. The rewards will outweight the costs. That's not necessarily true. Could I have hired a more skilled programmer for the cost of free training I'm offering the maintenance programmer? Could I have taught him the equivalent skills in some other way for less money? If so, then I'm wasting time and money bringing him up to speed by mentoring him.

      And if I can teach my senior programmers to write clearly in the first place, 90% of the time I'll be able to let my junior coder just fix things. 10% of the time, he'll have to call in someone more senior to explain things, but the cost savings are obvious. I'm not paying the surgeon to watch the janitor sweep the floors.

      No one needs to know that you passed grade 13 English with a 97% average"

      Then why is your highest priority item?

      "As others have mentioned, spelling and grammer are very important. Learn to express yourself in English, first."

      There's no contradiction: good spelling and grammar are very important. Unfortunately, deliberately using a complex vocabulary will often give you good marks in high school English. However, you'll still fail any technical writing course you take, if your vocabulary choices confuse your target audience. Computer code and comments are a form of technical writing: it's not about creative personal expression, except perhaps for code written at home for fun. In the business world, confusion costs money.

      To further clarify: people should know that you're fluent in English, or rather, it should never become obvious to the reader that you're not. And they certainly shouldn't have to suffer through a pompous display of unnecessary vocabulary to just to understand your comments, or your code.
      --
      Ytrew

        And if I can teach my senior programmers to write clearly in the first place, 90% of the time I'll be able to let my junior coder just fix things. 10% of the time, he'll have to call in someone more senior to explain things ...

        The tricky bit is determining whether the junior coder can recognise the 10% he can't fix himself.

        Hugo

        "After all, aren't all computer programmers in some sense just "semi-skilled" computer engineers:"

        That one sentence betrays the source on much of your misunderstanding. So much so, that countering many of your other statements is pointless in it's light.

        If you believe that programming is "semi-skilled", and a branch of electronic engineering, it is easy to see how you can equate software maintenance with re-fueling a vehicle or topping up the fluids. That type of vehicle maintenance is to do with replacement of consumables. Software has no equivalent unless you are going to suggest that putting a new writable CD in the drive or paper in the printer is a "software mainenance" task?

        Software maintenance is more akin to re-engineering the suspension when it fails to meet the ride or handling characteristics required; or altering the fuel/air mixture to compensate for high altitude use. To be able to perform this type of maintenance requires the maintainer to have a full understanding of the principles that underly the original design in order that they can re-engineer the appropriate components to compensate for the inadaquacies.

        The role of software mainenance often requires greater skills than the original programmer, because an underlying principle of software mainenance is that of "least change". Often the easiest way to correct a bug would be to re-write a large swath of code surrounding it. Doing so entails huge risk, because of knock-on effects, and huge cost, because the larger the scope of the change, the more re-testing and proving requires.

        The single biggest source of errors and unnecessary costs in software are those that come about as a result of viewing the mainenance role as a second fiddle, lesser skill. It isn't.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://424288]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others pondering the Monastery: (4)
As of 2024-03-28 18:30 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found