Writing good code - aka software quality

1

If you’re writing code just for yourself, then maybe quality isn’t so important - as long as if works, then it works!

But if you’re delivering code to someone else, like, your providing a library, then code quality matters. Oh, it doesn’t matter? Then you like being woken at 3am with messages from angry users that cant make your code work?!

Let’s talk about code quality!

For me, the key tenets to deliverable code are:

  • write some documentation first, to see from the outside what I’m trying to achieve

  • then sketch out test cases and key interfaces in parallel to see how it works from the inside

  • then flesh out the details (adding to both documentation and unit tests) as the main implementation as details become clearer.

The key aspect is docs and testing - the docs mean that others can understand what you have provided, and the tests ensure that what you have provided works as you intend!

This has worked for me in producing deliverable code - what works for you? Something else? Please share!

2 Likes
2

I own [this shirt, because it’s funny][1]… but it bothers me a little bit at the same time because I also own a shirt that says “Prefectionist.” ¹

Software quality to me means to have values and justification for doing things a certain way, and not just because it’s easier… but because it’s the right way.

Software quality to me means to stay open minded about your values, new values can be learned when appropriately justified.

Software quality to me means you don’t need a 100 page document to explain how your code works. You can look at the code, start at main() and figure it out. It’s reverse engineerable by mere mortals.

Software quality to me means you took the time to prepare for the worst real-time situations that could popup in the future, whether you think they are really likely to happen or not.

Software quality to me means you’ve assumed upfront your code will do something you didn’t intend so it’s structured to fail-safe when human safety is a concern.

Software quality to me means it’s not done until I’ve commented it properly, held a code review with my peers… explained how my code works and openly considered their feedback and made changes appropriately, written a firmware validation test plan and executed it, stored the complete project in version control software with all instructions on how to compile and deploy.

Software quality to me means I know it’s not really done until I’ve come to terms that I will no longer support it, because as time moves forward… code always has the possibility to change for any unknown reason.

Software quality to me means if I don’t comment and document it as I writing it (i.e. NOW), if will never get done because there is always the next project tugging at me just as soon as this one “appears” to be functional.

I’d be curious to know how you document your state diagrams. Sometimes I use excel tables, some times visio, word or even framemaker to make a more traditional state diagram. Other times I’ve used a mind map. When it starts to get complicated, I often wish there was a good tool to write it out logically like a table, but then have the flow chart part of it auto generated by the table. Some people can’t “see” how it works as a table, and others can’t follow a simple flow chart or state diagram… so you kind of need both. Any good free or cheap tools for this you use?

I don’t typically write unit tests, because most of my issues seems to be real-time functional issues that I haven’t found a unit test that would automatically find. So a firmware validation test plan that executes functional testing with many different worst case conditions seems to be the best way to find these subtle problems. Regression testing with many functional tests is a completely PITA though, but unit testing alone wouldn’t make me feel comfortable. That said I would like to start adding unit tests to my code.

¹ if you caught the typo, then you’re a perfectionist as well! It’s a cool shirt.
[1]: http://www.thinkgeek.com/product/f141/?srp=6

2 Likes
3

Cool response, and loved the shirt! You said a lot, which I and others will surely pick up on later!

One point that caught my eye - you mention unit tests and real time testing - there are more tests than just unit tests - there are tests that can attempt to stress your code just as it would in real life - such as stress tests You write a harness that simulates the realtime behaviour as best as you can. Sure it can be difficult, so a quality regime can also involve code analysis - but a solid test really does put minds at ease.

As always, the point of testing (at any level) is to find the problems before your customers do.

1 Like
4

I spend around 30% of my time writing unit test - which I think is typical. The more lines of code, the more essential writing unit tests is. I dont know what is a typical line of code count but mine runs between 25% to 50% of the total code is unit tests.

I find that writing my code against unit tests helps me write better code. Writing unit tests which runs on specialized hardware or has a UI is usually harder.