Writing Quality Software - Code

Coding is bringing the architecture and design to life. Making the idea work. Correct coding is more than just writing code that runs and do what it supposed to do. Correct coding is about making sure the architectural principles are applied, the code is readable and maintainable, self explanatory and self debuggable. Keep in mind that code is meant to be read much more than it is meant to be written.

Debuggable Code

What exactly is “debuggable code”? Well, I would say a debuggable code is a code that helps you find where the errors are as you run into them. This can be done by:

• Emitting enough logs where applicable.
• Not “swallowing” exceptions.
• Placing a method result in a local variable and returning it, rather than return a computation.
• Preferring a full if/else when needed for populating a variable over the shorter form of x?a:b.
• Breaking lines between different statements, such as
  if (something) return;
  which is not debuggable, since you can’t place a breakpoint on the ‘return’.

Generally, if you try to debug a section in your code and think it is too hard to debug because the debugger is not enough feature rich, think again how you can change your code to fit the debugger limitations.

Correct Casting

Scott Peterson posted this post about casting best practices. There are several things I would like to add upon.
First, when you expect a specific object type, prefer static cast, even in the case of a publicly visible method. The reason is that you would like the CLR to check the type for you and throw the relevant exception. Why? The alternative is you doing it yourself and responding correctly. Most people would simply “swallow” that error, which will yield bizarre errors elsewhere (most common ones are a null reference exception much deeper in the code, and it would be a very tedious work figuring out what went wrong).

Readable Code

For each project, select a standard and stick with it. Keep in mind that in some cases you might need to read the code you’ve written outside the IDE. This means you won’t have all the cool features like tooltips specifying a member type, go to member, find member references, etc. You want to write code that will be easier to understand without jumping up and down the file.
While it sounds like the Hungarian Notation might sound like a good idea (you can know the type and scope just by looking at the member name), it is a very unreadable notation. I like the naming that adds “m_” and “s_” prefixes to class members and static members respectively, but I hate the addition of “p_” prefix to parameters as I’ve seen in several places. So basically, it is all about readability. Whatever you choose, make sure it is easy to read outside an IDE (using notepad is a good test case), and stick with it.
Another aspect of readable code relates to indentation. Indentation is not an option, my friends. It’s a must, and its better be done right. Select your favorite method of indentation (most common methods include 4 characters wide, 8 characters wide and “smart”), and make sure all indentations are using the same method (spaces or tabs). I personally believe that spaces are the best way to go (along with monospaced font), since the overall code “design” is kept in all editors. Liran Chen has a post about an indentation issue in Visual Studio (in Hebrew).

Spelling

Don’t underestimate correct spelling. And prefer English in your code and comments over any other language. This will be used as a standard that will ease the process of joining new developers to the project. Minimize the use abbreviations and slang. It doesn’t come out nice, and tend to look unprofessional.

These are my two cents of how to write better code, and there’s much more to write on that subject. Maybe in one of my next posts.

Update

Just found this post regarding programming:

http://sites.google.com/site/yacoset/Home/signs-that-you-re-a-bad-programmer

I find it true, helpful and funny.

Writing Quality Software – Quality Assurance

One must not underestimate the necessity of the QA team.
Quality Assurance (QA), the guys that test the software designed by the engineers and written by the developers. Their mission is to make sure that the software does what it needs to do, and do it well. They are also the first users of the software so they have the best review and criticism about the visual design and usability.
A developer needs to learn to listen to the QA team notes. The QA team, on the other hand, must learn how to note.
In order to really understand this, lets check things more thoroughly:
First of all, the role of the QA team versus the role of the development team in terms of software operability:
No QA team – Bad software; No development team – No software.
That said, we now need understand that the two teams must work together in order to create good software.

Writing Quality Software - Architecture

Designing the architecture of software is very important phase in the software lifecycle.

Rules of thumb:

A good piece of software would follow several rules of thumb:

• Reusability – The piece of software should be as reusable as possible (unless it is applicative), and reuse other components as much as possible.
• Extensibility – The piece of software should be as extensible as possible – i.e. have enough places which other developers (or the original developer in a later time) can use to add more functionality.
• Functionality – The piece of software should make the life of its user easier. The 80-20 rule would fit here (at least 80% of the time…)
• Order – The piece of software should be organized for easy finding of each piece of code, and easy thinking of a good place for a new piece of code.
• Traceability – The piece of software should log its actions in details, preferably in different levels of detail. Usage of extensible logging libraries (such as log4net) are welcome.
• Security – The piece of software should not reveal security leaks, that would allow malicious code to abuse (I am talking about things like code injection, unauthorized privileges modification, system denial of service, etc.)
• Portability – The piece of software should be as portable as possible. Not necessarily between operating systems, but generally between computers. Zero installation (aka -xcopy deployment) is always welcome.