Good habits by Hormon

When I started my journey into vizrt systems world it seemed like everything was very simple to code. As the time passed my applications became more and more sophisticated and complex. It took little time for me to realize that sometimes I was getting lost in my code. It’s not a big deal, I just spent extra few minutes to find what I was looking for. Well, those extra minutes could become hours in few weeks. I decided, that from that moment I will try to follow some rules which will help me keep my code clean. Funny thing is those rules are really more like good habits: little effort -> reasonable productivity improvement.

Think before you do anything

The first step in every template/application/script development is design. Sit down and think of all the aspects of your problem. Analyze usage cases of your app, features it should include and how user interface should look. In my experiance actual coding is about 20% of development. Desing is much larger part.

Keep things clean

Basic thing which will help you to analyze your code even if it’s very long or fragmented in many files (or both :-) ) is to make it as plain looking as possible. Good programming requires certain esthetics. For me good source code is like a good prose. Both are textual, both have certain grammar and syntax, paragraphs (indents) and chapters (methods). Try thinking of your code as a novel. Make it as readable as possible.

Document your code as if someone else have to take it from you at any moment and from the first look had to know what it’s all about. This will help you in the future, because believe me or not, but that person probably will be you. Writing comments doesn’t take much time. Try to put them everywhere you use something that needs to be explained.

' initializes user form
Sub InitForm
  ' database connection status
  Dim connectionFlag
  ' establish connection with database
  '   * returns flag indicating connection state
  '    -1 - not connected
  '    0  - connection established
  '    >0 - connection error - message placed in err_msg global variable
  connectionFlag = InitializeDatabase()
  if (connectionFlag = 0) then
    ' query database for most current data
    ' and place results in controls on the form
    InitializeInterface()
  end if
End sub

Next time you come back to this part you won’t need to think what is going on there. Put comments both on methods and variables/fields. As shown in sample code above when we take a look at connectionFlag variable we know what it is and just before it is used we know what values we can expect.

Avoid using method/variable/field names which can mislead you or don’t tell you anything. When you need new variable to store animation state – call it animationState or animation_state instead of s or as. When you think of a name for some method which will aquire data from database call it AquireData or GetData rather than GD or Get. Also always try to place comment about the results you expect. Believe me – in the future you won’t regret this extra time you spent doing this

Be “lazy”

I have confession to make. I’m very lazy in programming. But being lazy not always mean a bad thing. In fact when you think of it – it can make your life much easier. Programming is a thing a lot of people are more or less familiar with. But despite your knowledge you can always allow yourself for a little laziness.

Consider following example: We have to design a template in VCP (Viz Content Pilot) to manage single scene in a certain way. The scene has five directors with following names: DirectorA, DirectorB, DirectorC, DirectorD and DirectorE. We want to be able to trigger every director separately from our template. So we place five buttons on a form and attach OnClick event to each one of them. Our code looks like this:

'---------------------------
Sub Button1Click(Sender)
  buffer_clear
  buffer_put "-1 " & SCENE_NAME & "*STAGE*DIRECTOR*DirectorA START"
  buffer_send MainMachine
End Sub
'---------------------------
Sub Button2Click(Sender)
  buffer_clear
  buffer_put "-1 " & SCENE_NAME & "*STAGE*DIRECTOR*DirectorB START"
  buffer_send MainMachine
End Sub
'---------------------------
Sub Button3Click(Sender)
  buffer_clear
  buffer_put "-1 " & SCENE_NAME & "*STAGE*DIRECTOR*DirectorC START"
  buffer_send MainMachine
End Sub
'---------------------------
Sub Button4Click(Sender)
  buffer_clear
  buffer_put "-1 " & SCENE_NAME & "*STAGE*DIRECTOR*DirectorD START"
  buffer_send MainMachine
End Sub
'---------------------------
Sub Button5Click(Sender)
  buffer_clear
  buffer_put "-1 " & SCENE_NAME & "*STAGE*DIRECTOR*DirectorE START"
  buffer_send MainMachine
End Sub

Well it works ok, but does it have to be so long? Do we really need to implement five click handlers? No we don’t. We can always take seemingly longer way to do this. Let’s change names of all buttons placed on the form with following pattern:

• “Button1″ to “btnShowDirectorA”
• “Button2″ to “btnShowDirectorB”
• and so on…

Now we implement single click handler and link it to OnClick event of each button

Sub btnShowClick(Sender)
  Dim directorName
  ' get name of proper director from control name
  directorName = Replace(Sender.Name, "btnShow", "")

  ' send viz command with director name inserted dynamically
  buffer_clear
  buffer_put "-1 " & SCENE_NAME & "*STAGE*DIRECTOR*" & directorName & " START"
  buffer_send MainMachine
End Sub

It wasn’t so hard, was it? Actually by taking second approach we made our lifes’ easier, bacause now if we’ll need to modify something – we have everything in one place.

Avoid code duplication

I can think of at least two reasons why most of people duplicate parts of their own code. First is they’re in hurry and second: they just don’t care at that moment if their code is clean. Well, both of this explanations have flaws. Primo: it takes much more time to do copy-paste operations than to implement single method with some some parameters and just use it in our code. Secundo: if for some reason our code will turn out to be faulty – we’ll have to change it everywhere and not just in one place.

Wrap everything you use more than once in function or method. You will see that after short time this additional effort will pay off.

Communicate

I cannot really decide, but probably the most important thing is to communicate with people which will use your application or template. They often have different perspective on the problem and can really help you find solution to it. Also they can have ideas or wishes which will make your application more usefull – almost always these ideas are very easy to implement. There is another “plus” – when someone makes suggestion and you implement it, this person has a feeling of being a part of development process. Those people almost always are more into learning how to use your software, thus, they use it the way it was desinged to, thus, less errors on air. :-)

That’s basically it. I’m curious if you have similar experiances. Please feel free to put some comments, they are all very appreciated.