Beefy Boxes and Bandwidth Generously Provided by pair Networks
The stupid question is the question not asked

"The Work of a Stranger ..."

by sundialsvc4 (Abbot)
on May 09, 2012 at 20:55 UTC ( [id://969706]=perlmeditation: print w/replies, xml ) Need Help??

A very strange thing happens when you have been in the business of software development for more than thirty(!!) years and when you subsequently (re-)encounter your own source-code (in whatever language it may be)...

It is:   the work of a magnificent stranger.

On the one hand, you recognize it to be excellent and thorough work.   On the other hand, you do not recognize it as your work at all.

No matter what sort of work we are doing, and no matter in what context, there is always a combination of “concerns” that present themselves to us ... and they are indeed very different:

  1. Temporal concerns:   In order to “get the job done,” at this particular moment with this particular tool (be it Perl or what-have-you...), these are “the immediate concerns of the moment and of the context.”   These are “the hoops that I am obliged right-now to jump through, just in order to Get The Job Done.™”
  2. Universal concerns:   It does not matter one whit what language I am using at the moment ... in order to solve “this sort of problem,” I must attend to “this.”

When we are writing computer software “in the language, in the moment,” we naturally tend to become absorbed in the first group of concerns.   But, my Meditation is, perhaps we ought to be more concerned with the second group.

I shall simply take it for granted that anyone to whom I am speaking “routinely” shifts his or her attention during the course of any particular day i(a)/i between any one of several different programming languages, and i(b)/oi between software that is new and familiar, and software that is old and decidedly not.

“Temporal” concerns, as we well know by now, might be swept-away by a mere “vendor software upgrade.”   Someone out there up-and-decides that “the old way” is oldy-moldy and that “the new way” does everything including the making of Julienne Fries, and ... suddenly, we have lots of work to do.   Meanwhile, the (Universal...) purpose of the application has not changed one whit.

Temporal concerns, we also know all too well, can simply be erased by memory.   All of us have only so much capacity between our ears, and as we grow older we become more and more aware of just how small that space can be.   We switched-away from project-X, which we wrote, to project-Y, which we also wrote, and now we must switch back, and ... (!!!)

What, then, can we do with a project, “as we leave it behind,” to make it somehow less “the work of a stranger” when we are obliged to take it up again?

Another, equally valid, way of looking at this problem is as follows.   When we set the problem aside the first time, we did so because at that time we thought it was “complete.”   And so, the reason why we are now taking it up again at a later date is because those requirements have now changed.”   Given that this, indeed, is a fact of business life ... what ought we have done, when writing the code the first time, to expedite the process of re-preparing ourselves to make proper changes to it, some (months|years) later?

Replies are listed 'Best First'.
Re: "The Work of a Stranger ..."
by jdporter (Paladin) on May 09, 2012 at 21:31 UTC
    ... the poorfellow who's going to maintain your code (which might be you!) -- Advanced Perl Programming, p. 69

    "maintain your code" "might be you"

    I reckon we are the only monastery ever to have a dungeon stuffed with 16,000 zombies.
Re: "The Work of a Stranger ..."
by Athanasius (Archbishop) on May 10, 2012 at 07:23 UTC

    Thanks, sundialsvc4, for a thought-provoking post. It got me thinking again about the general problem of documenting code, which is something I’ve been grappling with for a long time.

    We all know the necessity of writing useful comments in one’s code, and the difficulty of keeping them up-to-date as the code develops. I suppose we’ve all experienced that syncing feeling that comes from reading comments that contradict the code they “clarify”. For example, I recently downloaded the perl-5.14.2 source code, just to have a look. Being a top-down kind of thinker, I began by looking for the main() function, and found the file perl.c which contains the following comment:

    /* This file contains the top-level functions that are used to create, + use * and destroy a perl interpreter, plus the functions used by XS code +to * call back into perl. Note that it does not contain the actual main( +) * function of the interpreter; that can be found in perlmain.c */

    Great ... except that there is no file of that name in the distribution! I eventually tracked the main() I want down to perl-5.14.2/win32/runperl.c (at least, I think that’s the main() I want? :-/ ), so no major drama, but this does illustrate the syncing problem nicely. Perhaps a dynamic cross-referencing mechanism in POD could reduce this problem in Perl programmes? (Or does this already exist? I’ve only recently “discovered” POD, I don’t know it very well yet...)

    A related, and, to my mind, far greater problem relates to documentation of design. As a rule, even a moderately-sized project begins with a design of some sort, and, if more than one programmer is going to be involved, this design must naturally be documented in some form so that it can be communicated from the designer(s) to the other programmer(s). Yet how often does this design documentation make its way into the code base repository? Perhaps management omit it from the code base to safeguard confidentiality? Or perhaps the design document(s), because they are stand-alone files and not part of the code, are omitted because they just don’t seem to “fit”? Whatever the reason, the result is too often a code base in which the (to my mind) most-important-documentation-of-all is missing. Sure, the design is implicit in the code; but, the whole point of documentation is to make the implicit explicit, right?

    So, to answer the question:

    what ought we have done, when writing the code the first time, to expedite the process of re-preparing ourselves to make proper changes to it, some (months|years) later?

    I suggest:

    • Document the design. Doesn’t need to be long and detailed; in fact, this is a case where less is probably more. Just a summary explaining what the major components of the programme are, how they fit together, and why the programme has been designed this way (and why possible alternatives were rejected). And include this document with the code base, perhaps by prepending it to the top-level code file, which is often quite short anyway.

    • Perform a documentation review a short time (say, a week) after the code has been “completed”. Yes, this requires self-discipline. Yes, managers have more urgent priorities. But do it anyway, whenever you can, paying particular attention to syncing issues and cross-references, and your colleagues (or your future self) will likely thank you for it down the road.

    Just my 2¢.


    Athanasius <°(((><contra mundum

Re: "The Work of a Stranger ..."
by planetscape (Chancellor) on May 10, 2012 at 03:35 UTC
    what ought we have done, when writing the code the first time, to expedite the process of re-preparing ourselves to make proper changes to it, some (months|years) later?

    Aw, hell. That can be s/(months|years)/(days|weeks)/; for me...


Re: "The Work of a Stranger ..."
by gregor42 (Parson) on May 10, 2012 at 12:14 UTC

    It is for precisely this reason why I am one of those truly annoying people who actually writes (a lot of) comments. I have come back to code after as few as 6 months & not recognized it whatsoever.

    (Dons Flame-retardant suit) This is especially true of perl code, since TIMTOWTDI, I often change my approach based on my latest definition of "elegant"...

    Upon reflection it occurs to me that when writing in a language that is new to me I often write pseudo-code skeletons in comments which I then fill in with the proper syntax once I figure out how to make it work. What I find interesting is that it's not a bad approach to take in general, but I seem to lose interest when fluency sets in.

    Wait! This isn't a Parachute, this is a Backpack!

      I'm in much the same position-- I've been writing software for about 30 years, but never as my main job, sometimes for fun/entertainment and sometimes for work.

      I often set code aside for months or years as I don't have time to work on it or get distracted by something else. I fortunately wrote some stuff in Turbo Pascal about 25 years ago (a Corewar implementation, fwiw) that I liked, and then went back to about a year later and tried to read. My reaction was "Wow, did I write this?". Even though it was broken into decent sized functions and they were labeled and lightly commented, I hadn't really explained anything at all of what was happening and why, and it took a long time to figure out.

      I now tend to write for my future self, knowing that I'm not going to remember any of it: Start with comments to describe what the program is going to do at each step, write the program, describe what it's doing and why as a I go. If it operates on external data that might change, I'll put in notes of what it's expecting.

        My idea of comments is, comments should be 1/3rd the size of the code they accompany. The comments should explain your design choice, potential future design choices you didn't do due to a lack of time, skills, research, profiling, benchmarking, performance, client demands, etc, all your rejected design choices and your rational for rejecting all of them. Someone, including you might come back and say "hey that works, you should've done it in the first place" at some later point. The whiteboard from the meeting you had with other devels, or the napkin or scratch paper you planed your design on is long gone if you come back to the code months or years later. The comments stay forever. The comments should, in some cases also summarize the behavior of the functions you didn't write but are using, if the docs of the function are extremely long (Microsoft), or are written with much "undefined" behavior and you are using that undefined behavior (Microsoft), or ridiculously short or none existent (auto generated garbage, examples are Azureus or Mozilla).

        Sadly in some places, programmers are encouraged, and its nearly a requirement to keep ones job, to write obfuscated comment-less unintelligible code to guarantee they have a job. Dead and unreachable code is also good. Exception handling code for impossible exceptions is good. If you to generate alot of work for youself, make a design policy, that 1 object/class's definition/interface can't take more than 1 screen, and the functions of that class in the code file can't take more than 2 screen fulls max and you wind up with inheritance charts that would take the surface area of a car to print on paper. It guarantees you will be employed since even if your client takes the code and gets "consultants" or contractors to look it over, they will return a quote of 100s or 1000s of hours or just cost plus to your boss. You salary looks alot cheaper to your boss suddenly.

      I can’t magine why you’d feel the need to don that flame-retardant bunny suit for making a pragmatic comment like that.   I rely much more on comments than on code for understanding even what I myself have done.   That is nothing more or less than a pragmatic survival skill.

      I also categorically reject the viewpoint of people who say, perhaps in the name of “don’t repeat yourself,” that you have to write code as succinctly as possible.   For example, I recently got lambasted by someone who didn’t like me writing this:

      if (something_1_fails()) { ... do something ... } if (something_2_fails()) { ... do the same thing ... }

      This person’s murderously-held opinion being that the only proper way to write it was:

      if (something_1_fails() || something_2_fails()) { ... do something ... }

      such that it was absolutely “my way or the highway.”   My contrasting point-of-view simply being that:

      • It makes absolutely no pragmatic difference to the Perl compiler and/or to a modern-day machine, but...
      • The day will come when you want to change that code, perhaps in some slight way, and now you find that you have coupled these two pieces of code and/or behavior tightly together.   The two responses might be identical now, but the reasons for those responses are not the same and in fact they never will be.
      • (Key Idea...) Whether the response today is identical or not is not the point; whether the code is “more efficient” today is also not the point:   the concerns are different, therefore in months and years to come there is no reason to suppose that the responses will be different.   In order to correctly maintain the “only proper way” code anytime in the future, you are going to have to figure out both routines and (correctly...) judge how to prize them apart.   What ought to be a “no-thought modification,” say to tweak an error-message, suddenly requires thought.   All to gain you ... what, exactly?   (A: nothing.)

      Your thoughts always become the thoughts of a stranger, and you always re-discover those thoughts every time you go back to any piece of code .. in any language.   How well you documented those thoughts, and how cleanly you made those thoughts, truly makes all the difference in the world over the sometimes decades-long life span of a commercial application.

Re: "The Work of a Stranger ..."
by sundialsvc4 (Abbot) on May 18, 2012 at 14:52 UTC

    On the same point ... I just had to dive into a logic problem in a twelve-year old application that I wrote.

    I was deathly afraid to touch it.   Because the logic is complex and, although I understood the ins-and-outs of the thing at that time, I had long since forgotten everything about it.   (I even found myself grepping for the location of key subroutines.)

    I was able to “bootstrap” back into that zone and to resolve the problem because of the application-specific knowledge that was embedded in those copious and detailed comments throughout the code.   At the time that I originally wrote the logic, and of course then understood what I was doing perfectly, I wrote paragraphs of comments and kept them.   What had become over time obtuse and arcane once again became clear.

Log In?

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlmeditation [id://969706]
Approved by Old_Gray_Bear
Front-paged by Arunbear
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others contemplating the Monastery: (1)
As of 2024-07-22 01:48 GMT
Find Nodes?
    Voting Booth?

    No recent polls found

    erzuuli‥ 🛈The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.