What is a "good" architecture?

Hopefully you recognise it when you see it...

I believe every system has an architecture, documented or not, and intended or not. So I think it is reasonable to discuss if the architecture of a system is good or not, and that the question if the architecture description is good is a different, but related question.

So what criteria could you use to establish if an architecture is good? Is it suitable for it's purpose is a more precise question? But this probably differs depending on the stakeholder, a system could be very nice and intuitive for the user, but very difficult to develop and maintain for the developers. In the rest of this blog post I will writing about goodness from a developer perspective (including the architect, if one is involved).

I think there are different levels of how well the architecture suits it's purpose to guide and control the implementation.

The ideal level is where the developer understands the architecture and following the architecture is the obvious way to implement something. Doing it differently is seen as more difficult and less elegant.

The next level is where the developer understands the architecture, is able to follow it on her own and can evaluate if the implementation follows the architecture or not. The developer also understands the "debt" that would occur if she deviates from the architecture, for example in terms of compromising some quality attributes. At both this and the previous level the developer can contribute to the design of the architecture itself, and an appointed architect doing the design may not always be necessary.

The developer may need continuous support from the architect to be able to understand the architecture when working. This is very common and requires more work and puts limits on the the ratio between the number of architects and developers in large projects.

The worst level is where the developer cannot understand the architecture and the only one that can determine if the implementation follows the architecture is the architect by reviews. This is very work intensive on the part of the architect. The architect is also viewed as a police that interferes with the developers rather than supporting them.

I have worked at all this four levels in various projects, and I think that you need to be on the upper two if you talk about a good architecture from a developer perspective. I also think that if you want to be truly agile in a self-organising team it is at the two top levels you nee to be.

Jävla skitsystem!

Pardon the Swedish!

The heading is actually the title of a Swedish book about how people can be stressed in a digital working environment. I think this is one of the most important books written about IT-systems and the problems they can bring on a personal level for the people who are forced to using them. Too bad is is not translated to English (yet?).
It is not a technical book, the primary audience are people using IT systems, secondly it is targeted at people planning and buying IT systems. It systematically lists 8 major stress factors and what can be done about them. Not all are caused by ignorant developers...
I think it is very valuable to read for people developing systems, so much I would make it mandatory reading for students in software engineering, if only it was published in English. There is some information in English, including a short slide presentation.

You can buy the book directly at the website or at major Swedish online bookstores.

Development tools

I think you should select the tool that supports the way you are working, not the other way around. This is one of the reasons I think tool discussions usually focus on the wrong thing. They tend to get very long-winded and troublesome since the underlying process is not clear or decided.
However if you are a small team, I think the following tools are of use to you regardless of what process you are using (the version control software are useful for any project size). Many of my students seem to use them when they are doing project work.

• Version One Team edition - A free tool that supports managing agile software development.
• Trac - An enhanced wiki and issue tracking system for software development projects.
• GIT - A free & open source, distributed version control system. I think it is a major upgrade compared to SVN, even if the initial learning curve is steep.
  If you run Windows I suggest you use TortoiseGIT as GIT client.
• Mercurial - A modern, open source, distributed version control system (sounds very similar to GIT?). I think the learning curve is not as steep as for GIT, and a transition from SVN is probably easier. TortoieseHG is a good client for Windows users and what I use myself.
  In this user-friendly, six-part tutorial, Joel Spolsky teaches you the key concepts.

If someone can comment with suggestions of free simple tools that supports testing/verification or integration I would be very grateful.

Confused by Simulink

The most common modelling tool in the automotive domain is Simulink. It started as a Matlab-based tool to graphically model and simulate differential equations needed in control design. Now it has expanded way beyond that to enable generation of production code for embedded controllers.

For someone like me, with a background in software and systems engineering and only the mandatory control engineering course, Simulink is confusing. Not the model elements as such, since it basically is an executable time-discrete data flow model. But the terminology used in the Simulink community is really confusing since they are using terms very common in software development, but with different meanings. I am not even sure the explanations below are valid...

Some examples:

• A layer in Simulink is not what what one usually calls a layer in software. What is called a layer in Simulink I would personally call a view since it adresss a specific concern, see some defintion of the J-MAAB layers here. But I have also seen a layer as something found at a certain level in a functional hierarchy (boxes in boxes...). Maybe these two even are the same in the Simulink world?
  A software layer would rather be called a subsystem in Simulink, but that is a generous interpretation from my side. (See Pattern-Oriented Software Architecture by Buschmann et al. for a definiton of software layer).
• There are classes and objects in Simulink. Data objects are used to "specify values, data types, tunability, value ranges, and other key attributes of block outputs and parameters", where blocks are the basic entities that one build the simulink model from.
  The Simulink software uses objects called data classes to define the properties of specific types of data objects." So in a sense the class is a template for the objects. On the other hand the data object does not specify a behaviour or input-output relationship. But classes seem also to be a special type of objects in thelast quote above. Ouch!
  Contrast this to common OO design where the class is the template for the object, which is the main item encapsulating both a behaviour and associated data. A block in Simulink most closely resembles a function in a procedural language such as C or Pascal.

The importance of the team

I am reviewing and grading documentation in a student project. Or rather 12 student projects, all trying to develop similar software. The context is this: The students work in teams of 6. Each student has a separate role; project manager, architect, designer, quality/testing responsible, GUI designer and communications expert (it is an peer-to-peer application based on TCP). Alla students have to write code, and in addition to this they are supposed to turn in documentation related to their role.

What strikes me is that in the teams with good documentation all documents are good, regardless of author. How come? There could be several explanations:

• Good students want to work with each other (they could choose their teammates, they weren't assigned by us teachers).
• In good teams they cooperate on everything, inlcuding reviewing each others documents. In not-so-good teams they instead might try to split the tasks and work as independently as possible.
• In the good teams there is an exceptional student that functions as a mentor to the others.
• Excellent documementation from one role supports the others in their roles, e.g. an excellent architeture description supports testing etc.
• The good teams had not only a notion about what to deliver when they started, they also had a good notion on how to do it early on, e.g. they discussed so they had a common understanding of coding responsibility (everybody had to write code) and they choose an interative process or SCRUM already the first week.
• The good teams started with coding as quickly as possible. This is counterintuitive, but I think they felt more comfortable spending time on documentation if they already had some prototype running.
• It seems that analysis paralysis actually produces worse documentation. I think this is due to an inability to focus on the vital concerns and stop when they are sufficiently covered.
• It is hard to excel if your teammates drag you down. This could explain why there are no groups where just one role shines above the rest.

I'm sure there could be other explanations that I didn't think of...

Improving quality with well-written requirements

I discussed with a colleague about how to improve specifications and we agreed that one of the actions that would yield quality improvements with very little investment was to educate people in our organisation on how to write good requirements.
Unfortunately such a course is not available internally at Volvo Cars (don't ask me why). But a search found some useful pages that could serve as an introduction:

• The Story of the Paperclip: Writing Good Functional Requirements from StartupCTO
• Writing Good Requirements – The Big Ten Rules from Tyner Blain
• Writing good requirements is a lot like writing good code by Jim Heumann, IBM
• Writing Good Requirements (A Requirements Working Group Information Report)
• SMART Requirements by Mike Mannion and Barry Keepence

Is software engineering immature?

Is software engineering an "immature" engineering discipline? I have often heard this both in presentations and in reading, for example SEMAT states on the homepage:

"Software engineering is gravely hampered today by immature practices."

If I draw parallels between software engineering and civil engineering (arguably the most mature engineering discipline) my spontaneous conclusion was: Yes, software engineering seems to be more like how cathedrals were built in medieval times. The construction of them were based on rules of thumb and the practical skills and experience of architects and stone masons instead of the type of engineering practices taught at universities today. Interestingly enough, one can still see the "successful" cathedrals still standing several centuries later. But it would have been impossible for the architect of  Lund Cathedral to build something like the nearby Turning Torso. So the engineering in civil engineering has certainly "matured".
But where is software engineering failing? Everyone has heard of software projects running over time, over budget or have not been used as intended (or not used at all). But wait a minute! Exactly the same thing is common within civil engineering as well. There are many examples from a single contractor renovating a small house up to world known buildings such as the Sydney Opera House:

"The original cost estimate in 1957 was £3,500,000 ($7 million). The original completion date set by the government was 26 January 1963 (Australia Day).[16] Thus, the project was completed ten years late and over-budget by more than fourteen times."

So in this respect software engineering is as immature as other engineering disciplines.
So what is the fuss about? I agree that there is no consensus in the software community on how to do the equivalence of structural mechanics calculations or stress tests. Are we more hampered by this lack of consensus on how to do engineering tasks than by the difficulty to run large projects, which seem to be common to other engineering disciplines?

Software testing

I have to admit it, I suck at software testing. I do believe in my naive notion of test-driven design, i.e. write the tests first and the program later. My problem is that I just don't have the skills of programming test cases.
Example: I wrote about the "walking skeleton" design principle some days ago.One could write a suitable set of test cases to ensure that the skeleton, with it's various units, always walks. The tests should automatically run before you check in more elaborate units, with more features in them. If the unit doesn't pass you know that you will have integration problems.

There are a lot of resources on testing out there, for example I got an introduction on creating JUnit test cases for Java programs from a colleague. Since I'm trying to learn Erlang I should probably look into EUNIT.
You should also read the blog thoughts from the test eye.

I started working with system integration testing at Volvo Cars many years ago. I learned the basics of test planning, writing test cases and report test results then. Probably very outdated since both it was ten years ago and since the automotive industry has never been on the cutting edge of software development practices. We still have a notion that a specification should be written so that it can easily be tested:

"This easily results in requirements being quantified and often in a contractual style, instead of describing the real needs and desires."

There are many other ways of Synthesizing Test Ideas!

So if experts on testing are open to the notion of having specifications focusing on understanding and real needs, why are we still clinging to contractual requirements ? Is it because of so much of the coding is outsourced in the autotmotive industry?

If one aspires to be a software architect I think working with verification & validation (testing) is a good starting point. You learn a lot about good, and bad, design when you are exposed to the errors and unintended behaviour in a system and the effects they have.

Books on programming embedded systems

I'm looking for a good text an programming embedded systems (for example an automotive ECU) but I can't find any that suits the bill. I was hoping to suggest something to students that avoids the trial and error learning methodology I had to endure.

A quick search on Amazon shows some which could be relevant:

• Programming Embedded Systems: With C and GNU Development Tools by Michael Barr and Anthony Massa
• An Embedded Software Primer by David E. Simon
• Embedded C by Michael J Pont
• Embedded Software Development with C by Kai Qian, David Den Haring and Li Cao

Especially the latter sounds interesting since I like the software architecture book from the same author.

I was thinking of writing a book myself on the subject. But it would mostly haven been a collection of data one can find on the internet with some detective work. Subjects to include would be:

• Introduction to C, since embedded systems are programmed in C. Period....
  I like K&R, but you can choose any book that suits the bill.
• Good coding practices in C, for example MISRA C rules.
  Read some example of MISRA C-rules here, here and here.
• RTOS basics, since this is what is used on most embedded systems.
  Read chapter 1 in the User & reference manual of rt:kernel from rt:labs for a good introduction. But personally I prefer the "run-to-completion" type of tasks which don't wait for external events for predictability.
• Interrupts, stacks, and memory handling - ISR, RAM, NVRAM, ROM, Flash and every other acronym you can think of...
• Development environments, and compilers for embedded development
  My experience is that this is pretty much decided by the OS you are using. I have experienced very mysterious bugs just by not having the correct compiler version, so I can' imagine what could happen when having a compiler from a different vendor... IAR graciously provides all of their manuals free of charge and their IDE and compilers on 30-day on a 30-day free trial.
• Various hardware on a typical embedded controller - Details on how to access hardware with code examples.
  You can see examples of typical hardware devices in the Freescale MC9S12XS256 Reference Manual, a typical automotive processor, especially chapter 10-19. Mind you that this manual is 738 pages long, so it's pedagogical value is limited.
• Debugging - Too much to cover for this blog post. This is the real dark arts...
• Architecture of embedded systems
  Almost all embedded systems are layered, but why? And how do you know which layers to have in your system? And how do you identify the tasks you should have when schedule the system?