-- Leo's gemini proxy

-- Connecting to ew.srht.site:1965...

-- Connected

-- Sending request

-- Meta line: 20 text/gemini


New big software project --- how hard can it be?

tags: software grumpy

The other day I talked to J and D, both leading a small company supporting others in IT based solutions. At one point the chat went along the lines of how to /properly/ boot a new software project. We had amazingly similar expectations and a very nice conversation about it. And G (leading another small software company) was all for it!

So I decided to write up, how I would try it --- however, I'm not a project manager, and I never will be one, because I chose not to. I would probably cause much grief to others. Noone wants that.

The new big software project

They all start with the first line of code, remember?

Revision 1

This is basically a "Hello, World!" program in the technology, that shall be used. However,

It is checked into a version control system --- no kidding!

Is is build on a build server and not on anyones workstation --- you bet!

It has a version number compiled in (and optionally a timestamp string in some not so obvious location)

It can be build on anyones workstation. But that stuff never reaches the target system.

Revision 2

Adds unit tests for this humble "Hello, World!" program

which are run automatically by the buildserver (just in case anyone thought their existance would be sufficient)

Revision 3

Automatically builds an installable software package in the target systems native format for such deployment

It goes without saying that from this day on I do not want to see anything copied over to the target machine manually! Ever! While software developers might believe "But this is the most normal thing to do, isn't it?" the answer is: "Not for anyone else!" Not for the product owner, not for the folks actually manufacturing the larger machine, where the target system is only one tiny component. Not for the support person, who has to install a new version either in the hall downstairs or (later) in some remote location without a working network connection.

Not a big deal, right?

Revision 3a (extra credit problem)

If there is the requirement, that this humble software shall only work, if it is installed on a target system blessed by the product owner (and not some cheaply copied thing from elsewhere), ADD IT NOW! If this is the requirement, impose it on everyone now. Everyone! Development, manufacturing, support. Make sure that the signing key does not live on anyones workstation (make friends with the IT department early). Also make sure that this key can be replaced at will and exercise it a few times. You might not make big friends this way, but otherwise it will not work when shipped. Garanteed.

Of course, you will be the first one to lock yourself out of the target system! And if someone gets around these measures, then your overall design is not good enough and needs repair. Spend bounties on every possibility found!

Revision 4

might add a simple GUI, where you can see the version information and click on [Done]

might add a database connector

However, in order to force separation between GUI and logic, this is the place to possibly enforce a command line interface. If this separation is not there right at the start, it might be impossible to implement later. If your program needs to talk to a real database system, add it now. And separate it well. Add automatic upgrades to the database structure now, while it is small. Implement the whole upgrade procedure in building, testing, packaging and installation.

Revision 4a (extra credit problem)

Devise an interface, such that external testing can access the inner state of the program, reading and stimulating! Implement a client, add the ability to measure the time for any reaction of the program to the last stimulus.

Revision 5

This revision will add the "Hello, World!" message in three more languages and a button/list to select between them.

one language using another script (e.g. Traditional Chinese or Devanagari)

one language running right-to-left (e.g. Arabic or Hebrew)

your local language, German in my case

And from this day the infrastructure is set up to actually create translations. There will be someone supervising this from now and meticulously check the rendering, the size of boxes, and whatever is involved to make this happen. If you do not demand translations from this early point, it is going to be an afterthought, easily visible for anyone who cares to look.

Revision 6

Tackles another, grossly underrated point: Logging.

Add logging, configurable per module on the usual levels.

A unique, numbered list of message IDs is maintained by a gnarly person who does not blindly approve of everything. Remember, at least some of this is customer facing text!

Add a widget to the GUI to see the log messages. The user facing log messages need to be translated, ¡por favór! But always show this odd message ID.

Add a utility to read a log file (or db) and replace the text with local translations --- but keep the time stamps and all the other filled in information intact, please!

Closely related to logging is reporting (or whatever the official term is). Some module does not get an answer anymore or has experienced a reset or an increasing number of malformed messages, whatever. There must be a way to contact the supervising system and expect an acknowlegement of sorts. There is neither acknowlegement in logging nor garanteed delivery, iirc.

Revision 7 (optional)

The stuff at my day job involves data aqcuisition and fancy making sense of this data. So devise an interface to dump real data or feed a dump back into the system. This must be reusable for several points along the data munging pipeline. If possible use something, that already exists.

This revision is obviously premature, we need some of the real stuff to make this happen.

Revision 8 (optional)

If target system is only one component in a bigger structure, devise another interface such that all components in said structure are able to announce themselves and register at the supervisor part of this game. Add requests from the supervisor and health status messages. Adding some thought into this sort of thing will often lead to diagnostics without opening the machine. And yes, the gnarly person from above might have a keen eye on those messages, too. No translations needed here, imho.

Extra credit problem: make sure, all components can be updated (software, firmware, gateware/vhdl, et al.) from the supervising system. Add these things into the installation package. I have seen systems you need to literally open to update some little used component. Not funny.

Extra credit problem: Make sure power up works, no matter the order in which components show up. Make sure power down works. Make sure power down works even if part of the system ist not functional any more. Make sure partial power up and/or spurious resets are reported and lead to working conditions automatically. There is no shortage of interesting phenomena in this part of the puzzle alone.


Only after this point we can start to add the real stuff. By no means this is a new thing. And by no means I am really qualified to make such bold statements. However, I suspect that grumpy old me would be removed from the project manager role at this point anyway, so don't listen too closely.




-- Response ended

-- Page fetched on Wed Oct 20 20:18:03 2021