On Variable names

So Brody, a college of mine, wrote a script to pull the entire history of a work item and all related work items. Those of you who do auditing in service manager, your ears are probably burning right now. This is an incredibly useful feature in the relational object data model that service manager implements. The ability to see, at a glance, all of the edits to a combination work item (like a change request and all of it’s component activities) is SUPER VALUABLE. He asked me to look over the script before he published it.

To paraphrase Joss Whedon; I am very smart. So when I say Brody is almost 10 years my junior, and he has a deeper grasp of the database and low level functionality of Ops Manager and Service Manager then I could hope to develop given those 10 years over again, I want you to take my full meaning.

Next is the bit where I start dumping on him.

The script he sent over was terrible. oh, It worked perfectly and functioned like a charm! but I couldn’t tell you why or how. It’s full of code segments like this:

  $item1 = New-Object PSObject
  $item1 | Add-member -type NoteProperty -Name 'Property' -Value $oldRel.Name
  $item1 | Add-member -type NoteProperty -Name 'OldValueorRemove' -Value $OldObject
  $item1 | Add-member -type NoteProperty -Name 'NewValueorAdd' -Value $NewObject
  $Propa += $item1
  $item1 = $null

There is no way I could tell you what the objective of this code block is. It LOOKS like he’s building a custom PowerShell object, and inserting several key-value pairs, but why this array of members instead of a Hash Table? what does $Item1 mean? If you saw that somewhere else in the code, would you be able to tell what was supposed to be in that variable?  what about $PropA and what’s it’s data type? why are we building this array of custom object anyways?

Code is a language; a way of representing a set of ideas and communicating them. Computer code is a dual purpose language: Your source needs to communicate it’s intent to both the compiler/interpreter/machine, and to other programmers who need to understand, maintain and modify it.

The machine may have no problem understanding the purpose and difference for the variables named $H and $HH, but I can’t. Without that understanding, I can make no comment on if they’re being used effectively, correctly, or meaningfully.

The following two code segments are functionally identical:

  $a |% { if ($_.P) {$b+=$_ }}

  # this takes an input array, looks at each item
  # verifies it has a property Printable that is true
  # and then adds it to the output
  Foreach ($Element in $InputArray) {
    If ($Element.Printable -eq $True) {
      $OutputArray.Add($Element)
    }
  }

But it should be clear which is preferred, and why.

Yes, I know, I use Egyptian brackets. I’m bad. it’s an old habit I developed programming in original basic in high school, where IF statements were declared with English-ish keywords, rather then proper brackets, so i just got used to the condition being on the same line as the code block.