By: John Wolnisty, Solutions Architect – Integration at Vertech
In programming, you learn a lot from mistakes (or what some call experience). Here’s a list of some of our best programming secrets, as well as a few things to avoid. These tips are geared toward C# programmers, but the principles can apply to any language.
1. Don’t do anything that makes your phone ring after 5 p.m.
This is your prime directive. Memorize it, frame it, tattoo it on your arm… whatever you have to do. In practice, this means:
- Don’t roll out changes at the end of the day, on a Friday, or before vacation.
- Don’t roll out anything you haven’t tested.
- Don’t go in with the attitude, “If something breaks, I can fix it easily.”
2. Organize your code.
This is your secondary directive. Use helpful comments and name variables to help the person reading your code 2 years from now to understand what is going on quickly. Of course, that person might be you!
- Be consistent. In .Net, Java, or any development environment for that matter, there are 15 ways to accomplish a task. Pick one and use it everywhere. This applies to:
– Variable, function & object naming
– Code layout (braces, indents and white space usage)
- Be clever but not too clever. It’s really cool to replace 100 lines of nonsense with 5 elegant lines of algorithmic bliss, but not if mere mortals need to read a large book to understand it.
- However, don’t “Code for Dummies.” Confidently assume the reader has a journeyman knowledge of the language.
3. Use comments to your advantage.
- Don’t explain code in code-speak. Assume the reader knows how to code in the language you are using. Comments like this are useless:
firingTime *= 1000; // multiply by 1000
Comment at the application level not the code level.
firingTime *= 1000; // Convert seconds to milliseconds
Anyone can see a value is multiplied by 1000, but the comment explains why.
- Use block comments over line comments. Usually, when code changes, the end of line comment doesn’t change with it. Again, explain what is going on in the real world.
* System returns the values with the units-per-volt already calculated
* we only need to convert the units from kPa to PSI,
* and the time to whole milliseconds rather than fractions of a second.
- Avoid Excessive Comments. A small block above a function is usually all that’s needed, but longer comments may be warranted if the code is particularly tricky.
- Use the “///” feature of Visual Studio to generate a comment block at the head of a routine.
- Always document side effects that the reader needs to be aware of.
4. Manage and understand technical debt.
Stop saying, “Oh I’ll fix that later,” or “I’ll get to it next release.” So often, quick and dirty code labeled “temporary” is still in use years later. This is bad technical debt.
However, there are times you may have to use some ugly code to get the job done. This is reasonable debt. Let’s look at an example.
Say you have a project that requires a data validation step with six sanity checks on the results. Being a sharp programmer, you know you should design a rules engine for validation. BUT doing that would exceed time and budget. So, you quickly write some code that does the job but stays within budget.
In cases like this, leave a comment block that states:
- You realize this code is ugly.
- An explanation for why it is that way.
- How you would have made it better if given more time.
5. Don’t spend too much time trying to understand bad code.
When you get the task of rewriting hopelessly bad code, stay focused and use a strategic approach.
- First, get the actual desired operational narrative from the customer. After all, you were hired to replace an application, not rewrite it.
- Then, learn how the existing app is used by the people that actually use it. They often tell a different story.
- Look at the old source code, but only AFTER you understand what needs to be done operationally.
- Ask tons of questions to avoid wasting hours looking at code that is no longer used.
- Finally, use the old code as a reference, not a blueprint.
We hope you found this list useful. And, as always, we’re here to help.
At Vertech, we believe there’s a human way to do industrial automation. Yes, we design bulletproof MES, SCADA, OT, and controls solutions that are a joy to use. But we’re also your long-term ally. No more endless change orders. No more partial solutions. We’re here to reduce your tech-related stress, not add to it. And who knows? You might even enjoy the process.
Learn more at vertech.com
Register for the Council’s upcoming Phoenix and Tucson tech events and Optics Valley optics + photonics events.