in reply to "Designing" a Perl program

First of all, make sure you have the requirement documented precisely. You'll avoid a lot of problems by making sure that there are no undefined behaviours before you start.

Fundamentally, a design is a description of what the code will do, and how it will do it. The former is your interpretation of the spec (if you have one - if not the design is an opportunity to define one and make sure everyone agrees with it), and it's useful to cross check between them. The latter defines what you need to write, and need not be as precise.

Exactly what tools you use to describe it doesn't matter that much. Spending some time quantifying your ideas means that instead of changing your design when you've already started coding, both the bright ideas and the precise understanding that leads to design changes happen before you've started coding. That doesn't mean you won't change the design after you've started coding, but it reduces the chance of fundamental changes.

From a design point of view, I find UML, particularly class diagrams, enormously useful.
If you don't know UML, simple class diagrams (listing only attributes, methods and inheritance) are easy to learn - I found SAMS UML in 24 hours teaches this quite well, and provides useful guidance on software design as well.

If you want to go even simpler, a text document something like this: 

Object: Datasource

Attributes: connectionstring
            field

Methods:    read
            write


##################

Object: SQLDatasource
superclass: Datasource

Attributes: primarykey

Methods:    commit

[download]
would help you to focus (or equivalent - from your mention of UML I'm more or less assuming here that you are coding, or at least designing, from a more or less OO point of view).

Alternatively, flow charts are always a good fall back option, and easily understood even by the non-technical.

IME, you'll definitely gain a great deal of benefit from getting something substantial down in writing before you start coding.

It would also be worthwhile discussing the requirement with someone else, and getting them to look at your design in the context of the requirement. Talking over your design decisions can help to focus your mind, and input from other people always helps.

If this is related to the data consolidation requirement you posted about some time ago (Automating data loading into Oracle), at the very least your design should include something like this: 

SOURCEFIELD           TRANSFORMATION          TARGETFIELD
sourcedb.name         lowercase               targetdb.fullname
sourcedb.firstname    uppercase               targetdb.givenname
..

[download]

Since you have mentioned other people involved in the project talking about UML etc, it might be that there are people around with design experience. It could be worth your while discussing this with them, and getting their suggestions.

--------------------------------------------------------------

"If there is such a phenomenon as absolute evil, it consists in treating another human being as a thing."

John Brunner, "The Shockwave Rider".

Replies are listed 'Best First'.
Re^2: "Designing" a Perl program
by punkish (Priest) on Jan 14, 2006 at 19:54 UTC
    if this is related to the data consolidation requirement you posted about some time ago (Automating data loading into Oracle), at the very least your design should include something like this: 
    SOURCEFIELD           TRANSFORMATION          TARGETFIELD
sourcedb.name         lowercase               targetdb.fullname
sourcedb.firstname    uppercase               targetdb.givenname
..

    [download]

    <blushes>. Yes. Good eye. What you describe above is what I have come to call the "data mapping" document. That one I understand very well, and also understand its importance. I will be, of course, producing that.

    I am not sure at this time that my programming will be OO. I am very weak in OO, and I don't want to complicate my life for now. I mentioned UML because UML seems to be the technique du jour, and others in my team always mention it. I am not convinced they all know its utility. I know and understand flow charts, and intend to use them.

    I have to take source data, do magic to it, and stuff it into target tables. There is not much more to it at that level. Of course, the magic is complicated at times, and there are many different kinds of source data, and many different target tables.

    As I mentioned above in my reply to dragonchild's advice, I don't have any specs, and I don't understand what specs means in this context. From your advice, it seems I have a chance to make them up now. Please elaborate.

    --

    when small people start casting long shadows, it is time to go to bed
[reply]
[d/l]
      The spec (ification) tells you exactly what the problem is, i.e. a very precise version of the requirement. It tells you what the code has to do, without saying how it does it. It sounds like your data mapping document covers the bulk of that. The main thing about the spec is that it has agreement from the customer/your boss. "If it ain't in the spec, it ain't a bug" - if something doesn't work the way they expect, you should be able to say either "That's what the spec asks for" or "it isn't in the spec, so the behaviour is undefined". Ideally it should cover error cases etc (see my post in the other thread) as well as the data mapping.

      As far as design goes, your aims are:

      • To minimise code rewrites when you decide on a better way/make a mistake
      • To minimise code duplication
      • To make the code maintainable

      So in the main you should try and identify functionality that can be generalised and re-used by different functions. An example of that might be reading a db handle and performing transformations. There's no point in rewriting the while ($db->fetchrow_array) loop over and over again for every data source, so you'll probably want a general "read_datahandle" type of function. Data::Sync does this sort of task, and has general read & write methods, with the read method calling the appropriate transformation from a hash of coderefs keyed on the field name. Your requirement is probably more complex, but that's the general gist.

      Note that "there's no point" means "really try not to" - if you find a bug, you want to fix it in one place only; if you find a better way, you want to fix it in one place only, and you'll get really bored cutting and pasting the same code over and over.

      --------------------------------------------------------------

      "If there is such a phenomenon as absolute evil, it consists in treating another human being as a thing."

      John Brunner, "The Shockwave Rider".

[reply]
[d/l]
      If you like flowcharts, call them activity diagrams your friends will think they are UML.

      Phil

[reply]

In Section Seekers of Perl Wisdom