Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask

Re (tilly) 1: What you want and perl advocacy gone way wrong

by tilly (Archbishop)
on Jan 17, 2001 at 17:51 UTC ( #52509=note: print w/replies, xml ) Need Help??

in reply to What you want and perl advocacy gone way wrong
in thread module info

Actually most of what you are putting them down for is actually good advice. I likewise use few comments, use descriptive variable names, comment each function, etc. If you are relying on understanding comments rather than figuring out the code, you will have serious problems when the two disagree. And they will come to disagree over time - a general principle is that whenever two things need to stay in sync (eg comments and code, code in two places, etc) they inevitably will tend to not do so perfectly.

The real problem sounds like the use of global variables and a cut-and-paste methodology...

For the record the single most miserable piece of code that I have had the misfortune to meet was also one of the most straightforward and heavily commented. It was utterly impenetrable for the same reason that legalese is so hard to read.

  • Comment on Re (tilly) 1: What you want and perl advocacy gone way wrong

Replies are listed 'Best First'.
Re: Re (tilly) 1: What you want and perl advocacy gone way wrong
by salvadors (Pilgrim) on Jan 18, 2001 at 00:14 UTC

    Actually most of what you are putting them down for is actually good advice. I likewise use few comments, use descriptive variable names, comment each function, etc. If you are relying on understanding comments rather than figuring out the code, you will have serious problems when the two disagree.

    This is only true when you fall into the common trap of believing that comments are about explaining what you're doing in the code.

    Comments shouldn't be doing that. The code should be easy enough to follow that it's pretty clear what it's doing.

    Comments should be explaining WHY you're doing what you're doing. That's the bit that's hardest for someone to reconstruct after the event:

    "Yes, I can see that this loop is stepping through each item, building a hash of hashes of their info keyed by concatenating the title and the ID ... but WHY?"

    Once you realise it's so they can easily sort by title at the end, but that keying the hash on title wasn't enough as not every product had a unique title, then this makes sense. A well written comment would have made this process a lot easier, however.

    Comments are there mainly for the benefit of anyone who has to maintain your code later (including yourself!). They should explain all the bits where people will go "So, why exactly are they doing this like this?"


      I have posted enough code to this site, feel free to grab some and criticize.

      When I have examined my code in the past I find that my average function is about 10 lines. At a guess about 1/3 of those functions are public for whatever package they are in. Public functions get a comment. Function names are descriptive. Most variables are private to a function.

      If I cannot find a descriptive name for a 10 line function that gives you some idea why that function exists, that indicates a problem in how I am breaking the problem up.

      As with any personal style, it takes getting used to. And no, I don't always do a particulalry good job of it. But I don't think that modularizing less and commenting more would be an improvement.

        Yes, you're a good coder and you write clean code. There's very little you'll release to production that I can't figure out mechanically, and vice versa.

        There is, however, a great difference between understanding *what* you are doing and *why* you are doing it. This applies when working around bugs, when implementing business rules (which have, at best, a rather tenuous and dispassionate relationship with what we would call reality), and when doing things one way instead of another.

        How else will other good coders distinguish between personal preference (using defined tests on variables instead of oring them in place with default values) and operations and assumptions necessary for your code to work.

        I will only mention mere mortal programmers in passing.

        Having recently come up to speed on a large and complex and evolving codebase with minimal documentation and no further hints as to its name and nature, I will repeat that understanding the mechanics of a program is rarely beyond the abilities of your average caffiene-stymied simian.

        It is only discerning the will and the intent of the programmer that allows you to proceed without fear. That means coding by intent, expressing the design by way of metaphor (of which descriptive names play a part), and that means commenting your code with the assumptions you make and the reasons for any non-obvious decisions.

        tilly, while I agree in theory with what you are saying, I have a problem with this.

        Let's say I have a program that reads an initialization file, opens a data file, does some processing, summarizing, error reporting, etc. A simple outline of the program might run like this (sorry for the formatting):

        |--initialization--|--read .ini file | |--set globals | |--open files | main-|--process ledger--|--while not eof | | | | read next line |--addToProcessA | | | | | determine type--|--discard | | | | | write to file |--error reporting | |--termination-----|-- summarize results | write summary to file | close file
        If that's the case, it's relatively simple to document and follow the process flow. But, even for a simple process like this, here's what I usually find in production programs:
        read .ini file set globals open files while not eof read next line determine type addToProcessA -or- discard -or- error reporting end while write results summarize write summary to file close file
        It's a fairly linear run-through from top to bottom. There is little if any attempt to modularize the code. When that gets significantly larger, documentation becomes critical. I'm not disagreeing with how one should write the programs (small functions are the way to go), but many, if not most of the programmers that I have met simply don't appreciate this.

        As a side note, I find that even those who do appreciate this will often do the straight run-through rather than the modularization. I sometimes have that in my code (usually a sign that I've been given rotten specs).

        As a second side note, I just hacked together the example. There's no serious attempt to make the names more sensible or to really break it down properly. I'll call it pseudo-Warnier-Orr :-)


        Join the Perlmonks Setiathome Group or just click on the the link and check out our stats.

Re: Re (tilly) 1: What you want and perl advocacy gone way wrong
by jepri (Parson) on Jan 17, 2001 at 18:05 UTC
    I agree that all those things are good practise, but I feel there is more to it. A code map along the lines of "Well, we're going to have a main routine which fires up different function libraries depending on the cgi params, each case will be handled like this:....". You know, a general layout including future directions for the coders to go in. You need something like that when you have three people working on the same code.

    And yes, their main problem was that they didn't understand OO in the slightest, and were using global variables rather than presenting methods/data in a useful, consistant way. I suspect if they had sat down and written out what they were trying to do, they would have started to spot ways to improve their code. Perhaps that's program design versus programming. The code had apparently grown out of a 'quick hack' that someone put together one day, so it was kinda lumpy and directionless.

    In my mind good documentation is an art as much as coding or writing is. It isn't necessarily explaining what every line does. Having said that I'm off to edit my code snippit before somebody reads all my posts and plays spot the hippocritic bastard :)

    I didn't believe in evil until I dated it.

      IMHO you are describing the difference between programming and coding...

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://52509]
[Corion]: But people writing such code should document the objects they construct and why it makes sense for an object to be invisible as string while being true in a boolean context
[hippo]: That's equal parts clever and horrendous.
[Eily]: the overload version wouldn't return true with "$x" && !length $x though, I guess
[hippo]: The more I look at this code, the more $x is a plain old scalar and the more this condition will never be true. I'm calling it a bug at this point.
[hippo]: Thanks for your input which has soothed my sanity (a little)
[Corion]: Eily: Sure - if you force both things into stringy things, then you break that magic. But that would also mean that you changed the expression, as now $x = 0.00 will be true instead of false as it were before
[Corion]: Ah no, at least in my feeble experiments that doesn't change the meaning
[Corion]: We sell sanity in small packages ;)

How do I use this? | Other CB clients
Other Users?
Others pondering the Monastery: (8)
As of 2017-07-27 13:42 GMT
Find Nodes?
    Voting Booth?
    I came, I saw, I ...

    Results (413 votes). Check out past polls.