• A list of responsabilities needed to be fulfilled into order to meet the specifications (you do have specs, right?)
• An allocation of said responsabilities to the various subsystems
• An interface for each subsystem in order for the other subsystems to treat it like a black box

How you get there is irrelevant so long as you achieve those three items.

I mainly agree on this. As dragonchild says, you need to breakdown the system into a small chunks, decide how they interact with each other and document that.

However, I would suggest that you use same tools for documenting and designing the program as everybody else. That should make it easier in the future to read them, since the documentation is more consistent. You don't have to use all the tools all the time. For example if your solution doesn't involve object oriented code, UML most likely won't play as big role as it otherwise would.

Thankfully, I understand point #3 above. But, let me understand the first two --

"I want you to write me a program that will do this on that computer using the other tool". Let's break it down --

Responsibilities -- I have to write a program. That is my responsibility. The program has to do "this." That is the program's responsibility.

I am going to sound like a doofus, but what are the "specs"? Are this, that, and the other the specs? Generally, when I think of specs, I think the way a car has specs -- it gives 4 gallons to a mile, it seets a football team, and it is as tall as a horse. If I think if it that way, perhaps my program's specs might be that it has to do this in 24 hours, or it has to be done on that computer which has a hobbled operating system.

--

when small people start casting long shadows, it is time to go to bed

Wikipedia is always a good place to check. I generally use Google as a starting point.

---

My criteria for good software:

1. Does it work?
2. Can someone else come in, make a change, and be reasonably certain no bugs were introduced?

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]

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 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

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".

If you like flowcharts, call them activity diagrams your friends will think they are UML.

Phil

Before I start coding I write a test. :-)

Most projects I've seen are very simple, but grow in unatural complexity as you try to make it fool proof for an ever-wider audience.

First, you have to be able to picture it running in your mind. Then you have to ask if there are already tools available to turn your vision into code.

Regards (and ++ to dragonchild for the original node and pointer),

John Davies