Corporate Concept Architecture.
I was having a beer with one of the managers from where I work last night and as usual the topic turned to the systems we are using and as is usual the fact they don’t do what people want, the break down too often and they are not as cheap as promised. Essentially the problem, is how do you make the IT systems you use able to beat the IT quality problem.
IT Quality Triangle
Pick Any Two
This is in fact the same as the old joke about cars, “Looks Good” “Is Fast” “Is Cheap” pick any two.
continue reading »
December 06 2008 | Development | No Comments »
System Implementation; the bane of every system development.
You have a collection of software that you presumably spent months if not years developing, all of which depends on other pieces of software, which themselves are in a state of change and may even depend on the piece of software that you have just written. Assuming that you have followed some sort of methodology you have very carefully collected requirements, designed the system, written the code, unit tested it, functionally tested it, tested it as an integrated system, had your users test it, and finally by some miracle obtained a sign off from your customer that all is ready and it is time to turn it on.
So what happens. You organize a major production outage – often over a weekend, arrange for a dozen different groups of people to sit down in front of various computers and very carefully follow a hundred page thick set of manual instructions that tells them to start and stop various processes, back up various databases, manually change lines in a dozen files all in the correct order at precisely the right time, never making a typo….
So what’s wrong with this picture of a manual install of an IT system, apart from the fact that it seems to be standard practice in too many places.
I will let you think about that one…. **cough** you are a programmer **cough**
Let’s have a look at what a system implementation entails. In a nutshell what you are doing is making some changes to some files on a disk and adding some new files to the system, hopefully in such a way that if something goes wrong you can rollback to the state you were in before you started. You probably at the end of this exercise you will stop and restart some processes to ensure the new files are picked up. That’s it guys – it is the same on Unix, VMS, Windows and every other operating system from your iPod to the Space Shuttle. Now don’t give me any of this grief about “It’s got a database, or .jar files, cron jobs that all depend on each other and its too complicated” etc.
Something the technical types probably haven’t told you, or you forgot back in your first year lectures is that all software consists of collections of bits in various states arranged in things called files. All system and software work consists of changing the states of those bits.
So here are some tips.
Learn “make”
If you are on unix and call yourself a programmer, you really need to learn how to use the “make” utility. You have probably run the following sequence a hundred times.
$./configure
$make
$make install
See this site for details or try this google search.
Failing that, because to be honest “make” is non trivial.
Learn a scripting language.
Perl is a good one, but there are many others, then try the following exercises.
- Write a script that will create a temporary directory and put files in it.
- Write a script that will moves files from one directory to another.
- Write a script that will create a directory and then move a list of files from a known location into it.
- Write a script that will read a file and find a particular line.
- Write a script that will read a file, look for a particular line and write a new file with that line changed.
- Write a script that will start and stop a given process.
- Write a script that will run other scripts.
Now comes the hard part. Write a script that will stop a process, move a collection of files to a new directory, change the lines in a couple of these files, then move a collection of new files from some other directory into the original location and restart the process. To rollback you simply reverse the sequence. Stop the process, move the new files out and the old files back, restarting the process at the end.
By the way if you can’t do the previous – which amounts to a first year tutorial – what are you doing in the industry?
Predeploy
What does that mean? OK normally you will be doing all the hard work at some ridiculously late hour of the evening, you are tired, all your operations staff are home in bed, there may not even be anyone with system privileges in your data center at that time of night. Predeploy means to do 90% of the hack work during business hours when all your operations staff are on deck to help if something goes awry. All you want to be doing during your outage window is the simple task of moving files to their new locations.
Script Everything
You should never ever ever ever be reliant upon someone correctly typing in a stream of console commands at 3:00am. It should be idiot proof.
Put all variables in a single configuration file.
You should never ever have to pick through a hundred files to change the name of an installation disk.
Test Everything
Lets assume you have followed the rules above and you have written an installation script that will stop processes, move your old code somewhere safe, move in new files and restart the server. Do yourself a favor and test it. The installation script is a program developed just like the multi million dollar system you are using it to install and it needs to be treated in the same way. In fact your installation script if you do it properly will have requirements, a design and test results just like any other piece of software.
Run Things In Parallel.
The “Ok” we will install this piece and if that works, then the next piece etc strategy is complete bullshit. What happens if the last component fails six or seven hours into an eight hour window….. You are at the end of the outage and you now have to roll everything back. Stop your servers, move the files across and restart. If it fails you have to investigate and either fix or rollback anyway. In either case give yourself the largest window possible. Never ever allow yourself to be under time pressure, that is when mistakes happen.
Perform The Install When You Have A Full Backup Scheduled.
This is usually the time consuming part, waiting on a full backup to complete. So make it easy for yourself. Schedule the final cutover ,which should really only take an hour at most, to run at the end of a scheduled outage window.
So that’s it guys, believe me; as a programmer it is probably faster and easier to write the installation scripts than it is to write the hundred page document of obscure installations steps, attend all the implementation walkthroughs and struggle through a manual install under extreme time pressure at some awful hour of the morning.
October 13 2008 | Development | No Comments »
Self Documenting Code!!
The Doxygen documentation tool is a must have. I have been using it for some years now with no problems at all. Some major examples can be found here but perhaps the best way to show you it’s output is to link to some of my own code.
To produce the following I downloaded Doxygen and, pointed it at my code and simply ran it. I run it under Windows, but there are packages available for all sorts of operating systems. It will handle C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D.
NOTE: As this post is quite old and the documentation was chewing up a Gig on my hosting companies servers I have removed the old documentation
Client Code
Server Code
To see the whole class hierarchy you click on the “Class Hierarchy” tab at the top of the page and then “Go to the graphical class hierarchy”
A good example is one of the busy pieces of my code that is used as a base processing class called CProcessor from the Server Code link. This is the base class for a whole collection of different types of derived classes as you can see if you scroll down the class hierarchy page.
All those things with lines connected to CProcessor are derived classes that make use of the code in CProcessor. In practical terms this means that if I change CProcessor and make a mistake then all those derived classes will be impacted. Where this is an important analysis tool is that it enables one to see what does and what does not need testing. This enables testing effort to be directed where it is needed.
Now you can go further. If you click on the CProcessingBlock and scroll down you will see all the member functions. Now if you click on one of them – say CreateCellField you will see every function that calls CreateCellField. It might take a couple of seconds for the page to display – this is a big complex class.
Now I didn’t do anything to my code to prepare for this – simply ran it. It took me a couple of hours from scratch. In fact it took longer to upload the html it produced to this website than it did to produce the files.
Also if you play around you will see that the source code that produced the hierarchy can also be reached by clicking on the appropriate header file or source file name.
As a final comment. If you actually document your code as you go – something I find often starts with good intentions – you can embed comments into the code using three slashes /// rather than the traditional two // which will produce output similar to that found in my CAxisPlane class from my client.
What Does It Cost?
It is open source licensed, which makes it free, always a good thing. The following is from the Doxygen site.
Doxygen license
Copyright © 1997-2008 by Dimitri van Heesch.
Permission to use, copy, modify, and distribute this software and its documentation under the terms of the GNU General Public License is hereby granted. No representations are made about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty. See the GNU General Public License for more details.
Documents produced by doxygen are derivative works derived from the input used in their production; they are not affected by this license.
Final Comment
For the record this is the thesis version of my code StrawberryFields 1. It is unreleased as I don’t have the time to support it. The new code StrawberryFields 2 is essentially a total rewrite built around XML rather than MySQL with the editor being better suited to nanoscale research. In simple terms it uses all the lessons learned writing the first one, doing my thesis and figuring out what Mike Ford and associates really wanted rather than what I thought they wanted. But unfortunately the whole thing is on hold for a few years, at least until the economy sorts itself out.
Study the Mistress. Work is the Wife. If I want to spend time with the former then I have to pay my dues to the latter….
With things as they are that may be some years.
October 09 2008 | Development | No Comments »
