Clean Coders

  Code ReviewsWith the NASDAQ approaching its 2000 highs, I can see the reflection of the rising index in a Tech Boom 2.0 in North America. Start-ups appear to be popping up everywhere, with companies being awarded several multi-million dollar projects. This has caused a fresh flow of labor and capital into the software industry, with many people now acclaiming themselves as seasoned “Software Developers”. But my question today is this – Are there any clean coders out there? I’m not referring to software engineers who clutter their homes or create their own Leaning Tower of Pisas in their kitchen sinks (guilty). Reviewing existing software for a current project I’m working on has prompted me to post a topic on best software practices for creating clean code.

Software best practices should be discussed within software engineering teams within all corporations. Perhaps your company streamlined specific designs and implementations to be used across similar projects in your field. Or possibly each engineer has their own way of doing things which don’t quite jibe with your company’s objectives. Below are five methods you can use to improve your software team:

Streamline Design

Various powerful software development methodologies exist to facilitate software engineering projects. While the “Code-And-Fix” method may work for small-scale applications with no potential for future expansion, it is obviously not the best choice for complex projects with multiple team members. With larger teams, it is not uncommon to spot different styles of code, as no two engineers are created equally. For example, in this particular project I’m reviewing, TestStand is being used to automate testing, while LabVIEW is used as the base development platform. What I immediately notice is that ActiveX calls to the TestStand engine are sprinkled all over the sequence, while TestStand API is used within VIs to get and set properties. Essentially, two different styles to achieve the same objective – which creates confusion for a new team member just getting on-board. As a solution to this, design methodologies should be outlined from the start of the project, keeping the design as simple as possible and making use of reuse libraries if they are available.

Hack Hardcoding

Forcing variables within all layers of the code is a recipe for disaster. If you must hardcode values, such as configuration paths or initial flags, have those all centrally defined in a place which is easily accessible. For example, station properties can be stored in a configuration text file. Never-ever-ever hardcode values in your code unless you are positive they will never be changed and will not make life more difficult for another pair of eyes on your project. Hardcoding reduces possibility for software reuse and will prevent scalability as applications become larger and more complex.

Proper Documentation

Determining the reason you are documenting your code and your target audience are important during the documentation process. I cannot emphasize the number of times I’ve worked with reuse libraries or porting existing code which was either uncommented or poorly commented. Time should be allocated for your software development efforts to include documentation. In LabVIEW, it is best practice to document your VI, to use help tags and detailed help. It is also advisable to place free labels explaining any algorithms. Wires should be documented if they are not self-explanatory.

Poor Documentation:

//This is a random number generator
int * RandomNumberGenerator()
{
  int random;
  return random;
}

Better Documentation:

/********************************************************************************
  Overview: Determines a random number by using the time of day and dividing it by 
            the range of numbers wished to be randomly selected. 
  Inputs:   None
  Returns:  (int) random number generated
  *******************************************************************************/
int * RandomNumberGenerator()
{
  int random;
  //Explain algorithm here
  return random;
}

 

Delegation of Work

Your office junior typically shouldn’t be assigned to create a full software architecture (see image below for the consequences). Rather, they should be assigned to develop and implement set requirements for your project. Additionally, a team lead or project manager should evenly distribute work based on their team member’s strengths. Perhaps a Software Engineer has worked on database design and implementation on previous projects. Knowing your team and helping them improve themselves through opportunities is true teamwork in play.

Source Control

Various tools exist out there for source control and repositories. You may have heard of some of the following:

  • SubVersion
  • ClearCase
  • Perforce
  • Github
  • Project Locker
  • SourceSafe

I personally use Tortoise SVN as it’s free. Whichever method of source control you use, it’s highly recommended to centralize your software. Your team lead is typically assigned the gatekeeper of the source code, allowing up-revisions and scheduling periodic code reviews upon submission of new code. Check out this article why it’s highly recommended to use Source Control.

And finally, a sample VI I stumbled upon while browsing on LinkedIn the other day. A picture is worth 1000 words, but my guess is as good as anybody’s how many words this block diagram represents. I could only think of a three word summary to describe this masterpiece….

What.The.$!@#$!!!!

What.The.$!@#$!!!!

Clean Coders was last modified: May 2nd, 2014 by Paulo R

Leave a Reply

%d bloggers like this: