Writing Better Code

What is Code?

Those who write software refer to source code. This is human readable instructions for a computer to execute. Which either gets compiled to machine code in the instruction set the computer can execute, or is interpreted directly by a virtual machine. Java and Python are 2 languages that commonly use virtual machines. Whereas C or C++ are most likely to be compiled to machine code.

 

In this topic we will be talking about human readable source code.

 

Who writes Code?

Coders write Code. Sometimes they are also called Programmers, Hackers and Developers. To understand the difference, I like the definition given by Daniel Miessler who also blogs on technology topics.

 

Developer, Hacker, Programmer

Developer, Hacker, Programmer

  • Coder = Programmer = anyone who uses writes code
  • Hacker = Programmer who makes a specific something
  • Developer = Programmer who has been formally trained

So it is possible to be all three which is where we use formal methods and skills to make something specific by writing code to be executed on a computer.

Which brings us to the point of this post; “How to do it well“!

 

Writing Better Code

There is more than on dimension to this so for today I’ll focus on just two, and my thanks go to Johannes Brodwall at DZone for stimulating my thinking.

 

Don’t do it on your own

Not many people only ever write code on their own. There are exceptions. But for most of us working on any substantially sized system, the writing of the code is shared. One of our current projects is updating and improving on a code base that was started in 2009. So nine years ago. There have been 8 programmers contributing to it over those years and even though I was responsible for 80% of it originally I’ve contributing very little to the most recent round of new features or feature enhancements.

 

So principle number one is that great code comes from Collaboration. It needs to have the following qualities:

 

  • readable – first and foremost, write it for those who will follow
  • maintainable – lots of little principles like small commits, well abstracted, single responsibility
  • easy to modify
  • testable – test is a stakeholder so this should be considered in the design
  • reviewable

An interesting agile practice is Pair Programming. One types and the other reviews as they type. This allows more experienced programmers to teach others what they know by explaining as they go, and also to reduce the critical need for code reviews because the code is always reviewed. However don;t jump in too quickly if you think your partner is making a mistake. Maybe they are. Maybe you’ll learn something.

 

So code is made and maintained by a community in the long run. Whether is is an open community or a closed one inside a commercial business, it is more than 1 person’s responsibility.

 

So that is the first principle. You are writing for more than you. Make it useful to others.

 

Learn how to code On Purpose

There are many great resources you can draw on to learn how to code rather than by trial and error. I’ve bought many of the Pragmatic Bookshelf titles and found them very useful.

 

The Head First series from O’Reilly are also a great way to learn from the compiled wisdom of the industry to date. Start with Head First Software Development to get a good idea of generic Software Development best practice.

 

Head First Software Development

Head First Software Development

Explore methodologies and principles such as SOLID, Test Driven Development and many others. It will give you ideas. Very good ideas.

 

And there are many great online communities and resources you can leverage such as DZone. This is a very big topic so I’ll leave it at that. What I do recommend is that you don’t drift into this, you do it on purpose. Learn, adapt, and become better at coding.

 

The future will increasingly depend on two critical things:

 

  • better values based decisions about how we share this world together
  • better software – because we will eventually end up with software managing everything

Code well and prosper.

 

You can read the full post by Johannes Brodwall at how to write better code.

 

Successful Endeavours specialise in Electronics Design and Embedded Software Development, focusing on products that are intended to be Made In AustraliaRay Keefe has developed market leading electronics products in Australia for more than 30 years. This post is Copyright © 2018 Successful Endeavours Pty Ltd.

Software Development Metrics

Software Development Estimation

in Software Costing we looked at some typical ways of determining the likely cost of a Software Development project. One way was to look at how much typing was involved. This is not considered the best approach as the cartoon below demonstrated.

 

Software Estimation

Software Estimation

I prefer to spend more time thinking about the problem and less time typing. Among other things this reduces the amount of typing required.

 

The other example was by looking at the study by VDC Research where the median Software Development project had a cost of US$12.50 per line of code. Which is also very expensive by our reckoning. But these are actual figures. The hard part is working out how many lines of code (LOC) will be required before you have written them.

 

Estimation by Function Points

So I was interested when The Embedded Muse, a software development newsletter authored by Jack Ganssle, published some data from Capers Jones who is a legend in the Software Development industry for his statistics on the Software Development Process.

Capers Jones & Quote

Capers Jones & Quote

My first thought was that I fully agree with the quote. Let’s have a look at it in detail.

High-quality software is not expensive. High-quality software is faster and cheaper to build and maintain than low-quality software, from initial development all the way through total cost of ownership.

 

The assertion is that if you have a way to measure Software Quality, and you stick to good Software Development Process and the creation of High Quality Software, the overall cost will be lower. This might seems counter intuitive to some of our prospects given the development process requests we get, but I think it is spot on. Here are the other items of interest.

 

According to Capers Jones, a very rough guide to estimating the number of people needed on a project, and the project’s duration, is:

 

  • Number of developers = (function points)/150
  • Calendar months = (function points) x 0.4
  • One function point is approximately 130 lines of C Code

So for a typical 20,000 lines of C Code project, we would expect 154 function points with 1 developer required and it would take 5 years. If I look at one of the Industrial Control projects we did then that was 60,000 lines with 3 developers (that part works) and 8 months overall (rather than 5 years). So I’m not convinced the time component of the formula works. Maybe it is too heavily influenced by larger projects. But the number of developers seems to be about right.

 

Again, these are actual project figures and not some abstract model. And if you don’t use good Software Development Process then the cost of debugging and fixing issues in the field will typically dwarf the cost of writing the code.

 

Software Development Metrics

So I thought I’d do a summary of the Software Development Metrics we have accumulated over time as this may help with the Software Estimation process. This is what it looks like in our world of typically smaller projects (less than 100K LOC) reflected through the data above:

 

  • Number of developers = LOC  / 20,000
  • Number of months = LOC / ((number of developers) x 6600)
  • Cost of development = $4.80 per LOC

This assumes good process and average project difficulty. Things that will push a project way past this are code space constraints, processing power constraints, poorly defined requirements and substantial changes of direction mid project. But it does give some way to at least know the ballpark.

 

Successful Endeavours specialise in Electronics Design and Embedded Software Development, focusing on products that are intended to be Made In AustraliaRay Keefe has developed market leading electronics products in Australia for more than 30 years. This post is Copyright © 2018 Successful Endeavours Pty Ltd.

Embracing the Digital Future

Digital Tomorrow is Today

The most recent Casey Cardinia Business Group breakfast heard from Chris Riddell, futurist. This is a summary of what he said.

 

Chris Riddell - Futurist

Chris Riddell – Futurist

 

The future is already here. The digital revolution has happened. So what about tomorrow?

 

This is the question Chris posed to the room at the start of his presentation.

 

Chris asserts that the technological revolution has already happened. Now it is Velocity that counts. So what does Velocity mean?

 

In Software Development, Velocity refers to the rate with which you are completing a project. If Velocity is too low, you will not finish on time. Ideally Velocity is above the original planned value and you will deliver ahead of schedule. At the very least, this allows you time to test comprehensively. Projects running late often compromise on test in order to save time. This tactic usually adds time in the long run.

 

His first example was OTTO. This is a start-up of ex Google employees who are developing self-driving track technology that can be retrofitted to existing trucks. So you don’t need to design a new vehicle, you can add their system to your existing fleet. They have early adopted product in the market (delivering beer via self-driving trucks) and hope to be fully market ready in nine months. And uber bought OTTO. This rapid time to market is an example of the increasing Velocity available today.

 

OTTO self-driving truck

OTTO self-driving truck

 

A local example we are working with is Maintabase. This is a Melbourne based start-up that came to us 2 months ago with some “off the shelf” hardware to try and configure it as a demonstration of their asset management concept where you can monitor machine cycle and operating time automatically and identify when maintenance points will be reached. Like OTTO, this can be retrofitted to any existing machine. They were trying to use “off the shelf hardware” for good reason; low development cost. However the hardware was difficult to configure and use, not very flexible, and ultimately not what they wanted in a final product. It was never going to do what they needed and was only ever an interim measure. So we created the product they need and they are launching it at Future Assembly in the IoT Category.  So idea to launch in eight weeks!

 

Maintabase

Maintabase

 

And then there is Tesla who have reinvented the modern passenger automobile and already offer autonomous cars.

 

Tesla

Tesla

 

And now a medical example. 23 and Me will send you a DNA kit. You provide a saliva sample in the test tube they provide. They then send you a detailed report describing your genetic ancestry, what health issues you will expect have in the future and even what kind of children you will have with your partner (you need two samples for that). This was banned in the USA due to concerns about how to regulate it so they moved to Europe and launched there. Now they are also able to operate in the USA. Five years ago a service like this would have been prohibitively expensive. Now it is a very affordable tool to allow you to manage your life better.

 

23 and Me - Welcome to You

23 and Me – Welcome to You

 

We also see the huge burst of activity in Wearables that allow you to quantify things like quality of sleep, activity level and a whole range of health and other indicators. The Quantified Self requires measurement and these devices do a good deal of that already.

 

Lean Digital Start-Up

Computing technology is also changing so rapidly that you can do a hugely scalable start-up in a shed. This is technology going full circle. HP started in a shed. So did Google and Apple. The shed may become the new business launch model.

 

This allows a new class of business opportunities lumped under the banner of the Lean Start-Up. I’ve added “Digital” to the mix because there is a lot of emphasis now on being able to scale quickly. So we have the Lean Digital Start-Up. So low investment, low risk, potentially huge upside, potentially scalable. The failure rate of Lean Digital Start-Ups is unfortunately also huge. About 25 times the failure rate of conventional businesses. The risk due to failure is much lower and they can pivot rapidly. This is Agile applied to the Business Model.

 

Old world businesses are like huge plantations and have a specific focus and everything is about optimising that focal point. By comparison, the new business paradigm is like hacking your way through a rain forest looking for a breakthrough plant or animal that holds the cure to something incurable. The latter is a much more chaotic process and results are unpredictable.

 

Access to technology means that even mobile phone calls and SMS are old hat and is all about video, high speed data sharing and experience.

 

The Future What Next?

BMW have just celebrated 100 years in business. That is a great achievement. If you go back 50 years, it was all about the product, the technology, the reliability. Today it is all about the experience. And they are talking about selling transportation services rather than vehicles in 10 years time.

 

Super Fluidity is now the norm. You can transfer data almost instantly to anywhere in the world. Today you can design a product, send the file somewhere else on the planet and have it 3D printed. You can now 3D print food. Oreos can be custom designed by you and then made for you and shipped to your address.

 

Why is Google self driving cars happening? Google do search and other data stuff. The answer from Google is that a driver-less car is a mechanical problem that needs an information solution. And Google are an information solution company.

 

Why is Lego still in business? It is a plastic block. Easy to copy and many have done it. Yet today they are the most influential toy company in the world. Everything is about the user. You can design your own kit, select the blocks, buy it and have it delivered to your door. You can build it on screen, have it 3D rendered and sent to your device to show or share with your friends.

 

Apple have enough cash on their books to pay out Greece’s national debt three times over and still run their business for a year even with no sales. And they did it by making their product easy to use and putting a full ecosystem together to support the user.

 

Air bnb, uber, Spotify and many other companies are leveraging great user experiences and offering great value.

 

We are headed into an era of no screens, augmented reality and where the world is your screen and data is your overlay.

 

Pretty exciting times lay ahead as we catch up with the capability the Digital Revolution already lays before us.

 

Successful Endeavours specialise in Electronics Design and Embedded Software Development, focusing on products that are intended to be Made In Australia. Ray Keefe has developed market leading electronics products in Australia for more than 30 years. This post is Copyright © 2016 Successful Endeavours Pty Ltd.

Embedded Software Testing

Software Testing

I recently met with an Australian Software Development company, PepperStack, and we got onto the subject of Software Testing. As someone who began their career as an Electronics Hardware Engineer, one of the things I learnt was that you have to test thoroughly to be sure everything is working as it should be. With Electronics, if you make a mistake with an Engineering Calculation you can easily destroy things. This is sometimes referred to as “letting the smoke out”. So it was good to meet with others who believe in the same level of rigorous software unit, module and system testing that we do.

 

 

Some Engineering Humour

Which reminds me of a joke I once heard:

 

There are three Engineers in a car going for a drive. The first is a Mechanical Engineer, the second an Electronics Engineer and the third is a Software Engineer. Fortunately the Mechanical Engineer is driving because the brakes fail and they are going downhill. The Mechanical Engineer eventually brings the car safely to a halt and gets out to examine the hydraulic systems. The Electronics Engineer gets out and checks and body computer, ABS system and the power train CAN bus. The Software Engineer stays in the car and when queried about it says that they should all just get back in the car and see if it happens again!

 

Now don’t get me wrong, I’m not having a go at Software Engineers. The process of finding and eliminating faults is a very important part of the development cycle and is something that needs up front thinking and not just responding to symptoms. And the more complex or sophisticated a system is, that harder it is to fully test every possible response to every possible stimuli and after a certain point it becomes impractical to have 100% Test Coverage (every line of code has been executed through all of the possible states). The reason this is a bigger problem with Software Development is that the flexibility of software means that it is inherently complex and it takes skill and planning to manage that complexity so it is testable.

 

So here is the issue. More than any other discipline, faults can be experienced by an end user of a product under a situation or scenario you could not have proactively tested against before release. There are many potential reasons for this including:

  • change of hardware or operating system environment
  • new standards or protocols
  • the sheer number of potential combinations of drivers, peripherals, software and users
  • the product being used for a purpose it wasn’t originally designed for
  • gamma ray corruption of a memory location – I am getting esoteric now but in some areas like avionics and space this is a big threat

So how do you reduce the likelihood of these problems occurring?

 

 

Improving Software Quality

With many new products having Electronics and Embedded Software and the Software Development requiring 80% of the effort, it is important to delivery it as quickly and fault free as you can. The main weapons in your Software Quality arsenal have been known about for a long time but are, in our experience, just not used. These are:

  • Architectural Design – work out how the data and execution flow will happen and how you will manage the constraints
  • Functional Decomposition – divide and conquer but with an emphasis on how each module fits into the system and how the interfaces work in detail
  • Error handling – who will decide what to do with response codes – again this is data and execution flow and part of the architecture. In many cases exception management is at least 50% of the project.
  • Have an Integration Test Plan – some thing that proves the data and execution flow matches the architectural design. Too often “it builds” seems to be good enough here.
  • Unit Test modules – so you remove all the issues before adding them to the integration
  • Do the Integration Tests before you try system testing
  • Design modules so you can integrate them as shells then add functionality down the track
  • Have NVM and configuration data available at the beginning of the project and not as an after thought at the end
  • Have a System Test Plan and use it
  • Use some of the good practices of Test Driven Development – run the tests every time you change the code
  • Have a rationale for what level of Code Coverage you can accept
  • Have a rationale for what level of Churn you can accept – Churn is the percentage of the lines of code that have changed in the past time period. Usually either a week or month depending on the size of the project.
  • Use automated software quality tools. For instance we use both PC-Lint and RSM to automated many software quality metrics which saves a lot of time in Code Reviews
  • Use Code Reviews, also known as Software Peer Review. It really does save time.

Next I plan to look at what you can learn about software testing from a Squash Racquet.

 

Ray Keefe has been developing high quality and market leading electronics products in Australia for nearly 30 years. For more information go to his LinkedIn profile. This post is Copyright © 2010 Successful Endeavours Pty Ltd.

Improving Product Development Outcomes

In this post we will look at the Product Development Process and how to get improved outcomes. But first here is a fun graphic made from our logo.

Successful Endeavours - Making Electronics and Embedded Software Work

Successful Endeavours – Making Electronics and Embedded Software Work

Product Development Process

The Product Development Process is intended to reliably deliver new products for manufacture or distribution. This is a critical component of a Product Strategy where you are creating the product rather than sourcing it from a supplier. So you would think that it should be a highly optimised, well oiled machine that reliably delivers successful products. Alas that is not always the case. With 30 years of experience in Developing Products for a wide range of industries I have seen my share of projects handled well and not so well. Here are some general principles I have gleaned from my experience in Successful Product Development Projects:

  • Risks must be identified and managed. Track them and eliminate them as soon as possible.
  • Anything clever or tricky needs to be checked by someone else.
  • Everything else also gets checked. Design reviews, code walk-throughs and prototypes save time, money and heart ache later on.
  • Hold the timeline. Foster an attitude that slippage is not acceptable.
  • Test and check everything.
  • It’s not finished until no-one has to do another thing to it.

So six core principles. They are inter related of cousre. Let’s look at how these work out in practice.

 

Successful Product Development Principles

Lets look at how each of these priciples can be used to improve the likelihood of a Successful Product Development Project.

Risk ManagementRiskManagement

Risk Management is an old idea. Not surprising since risks have always existed. Did you know that during the Manhattan Project it was determined that there was a chance that a fission bomb could ignite the whole atmosphere ? Having got contradictory reports the argument was eventually settled by a report showing that although it was possible, it was unlikely. How comfortable would you feel running that risk ? Fortunately the average Development Project is dealing with much more mundane risks such as achieving Technical Requirements such as:

  • Power Consumption
  • Unit Manufacturing Cost
  • Performance Criteria

But the approach is still the same:

  • Identify the risk
  • Work out how to ameliorate the risk – reduce it – or eliminate it
  • Do tests to confirm the risk has been dealt with
  • Iterate until it is no longer a risk

Review the clever bits

Test Everything - Clever Design Needs Test

Test Everything – Clever Design Needs Test

Where possible, any particularly clever or tricky areas of the project need to be reviewed by someone not involved in the everyday work of the project. This is primarily to ensure that assumptions are challenged. If you can’t get an outsider to do the review, use a process like Six Thinking Hats by Edward De Bono which can allow team members to step outside their emotional and assumptive predispositions. Unchallenged assumptions are unmanaged risks.

 

Review the rest of the project

Test Everything

Review Everything

The astute amongst would have noticed that I am proposing everything gets reviewed. But the tricky bits get extra review. This section is for the regular bits. Reviews are an essential tool to find mistakes early and eliminate problems down the track. You don’t have to solve a problem you don’t have. Or as Jack Ganssle famously quipped “Skip Bugging To Speed Delivery”. That article refers to using Code Review and Design Review to find problems early and fix them so they don’t become much bigger problems later on. Imagine a scenario where a Software Bug causes an electric motor to try and spin backward every now and again and then corrected itself almost immediately. You would get a momentary shudder or jerk followed by correct motion and it would only happen every now and again. How would you determine that this was a software fault and where the fault lay? It could be symptomatic of any number of issues including Mechanical Design and Electrical Design. How about this similar real world case. I won’t mention the company, but their elevators had an Integer Overflow problem in the motor controller that caused the elevator to go in the wrong direction, about once a month, for half a floor. Very disconcerting to the passengers if they pressed up, and promptly dropped half a floor before then going up. Fortunately they found it and fixed it before it happened to someone at the top or bottom floor. All the Software Industry Metrics show for that for Software Development; Design Review, Code Review, Unit Tests and System Simulation save money and time. And yet in many projects they don’t happen enough or are done after the event as a Quality Assurance box ticking activity where they add mostly cost and little in the way of value. Lean Coding argues that you can reduce your Software Development Budget in particular by doing Code Inspections during the project as part of the Risk Management and Quality Management process. By reducing the bugging, you can reduce the debugging.

 

Stick to the Timeline

Project Development Timeline

Project Development Timeline

An attitude that the schedule slipping is normal can be very costly. Some examples of how to avoid this are:

  • Develop and Simulate the Software before the Hardware is ready
  • Prototype early and thoroughly
  • buy in IP where it makes financial sense – this can also reduce risk
  • get expert assistance with areas outside your competence
  • review regularly and honestly

As someone who has done a lot of team leading and project management, I have learned to ask about progress in more than one way. I find the following to be very common: Manager: “This module is estimated as 10 days of work to complete. How complete is it”? Developer: “About 80%”. Manager: “How many more days of work are required to fully finish everything”? Developer: “To fully finish everything, I would think 6 more days would cover it all”. The discrepancy is easy to spot. People estimate high on progress because they want to please. They also like to finish well so they tend to estimate conservatively on required effort. In practice the real answer lies somewhere between the 2 extremes. If the task had already consumed 6 days of effort then it is likely to run late. If you have ever built a house you might have experienced the knock on effect it has when one trades person doesn’t turn up and everyone else misses their scheduled action time because they are now waiting on a predecessor task, the trades person who has to come back again, before they can start their task. The same thing happens on projects. So fight hard to hold to the schedule. It is better to over resource a task (according to the plan) and get it done than to let everything and everyone slip which usually costs a lot more. Additionally, it is quite common that the later you are in the market, the lower the overall profit. So it is worth holding the schedule for this reason as well.

 

Test and Check Everything

Test Everything

Test Everything

This is another Risk Management related principle. Don’t assume it will be OK. Even if you have done it 100 times before, test it again this time. Make sure it really is OK. This ensures it really is 100% complete. This also implies that you are going to design things so they can be tested. Another principle. Design For Testability or sometimes called Design For Test. Do it. It will save you time, effort, money and sleep. Test Driven Development is another example of a Modern Development Methodology where you set up the test first then develop the product so it passes the test. If the Product Requirements change, you change the tests first, show that the old Product Design fails the test, then update the Product Design until it now passes the test.

 

It is not finished until no-one has to do anything else to it

Many tasks are called complete but they aren’t. The documents might be checked into the Revision Control System, also known as a Version Control System or Version Management System, but it isn’t complete until it is 100% tested, 100% integrated, 100% reviewed and 100% signed off and no-one has to do another thing. This also means that when tasks are identified that weren’t thought of in the original Project Plan, you then add them and don’t try and fiddle them into existing tasks. This is different to working out the fine detail of a task and realising it is under resourced or over resourced on the Project Plan. You also want the extra tasks visible on the Project Management Plan so when you do the next project you have evidence that they were required last time and can make allowances for them.

 

Trip Assurance for Developers

Satisfaction Guaranteed

Satisfaction Guaranteed

In marketing, the term Trip Assurance refers to the client having a clear expectation of this transaction or experience being a good one, just like every other one has been. I think we can begin to develop some of the same as developers whereby projects can be routinely good experiences and likely to be so each time.

 

This post is also available as an eZine article with Expert Author classification.

 

Ray Keefe has been developing high quality and market leading electronics products in Australia for nearly 30 years. For more information go to his LinkedIn profile. This post is Copyright © Successful Endeavours Pty Ltd.