As I work along with some legacy code for my capstone project, I get to a very complicated and long JavaScript file. To my surprise, the functions (and the variables to go along with them) are not named in any sort of descriptive manner, nor are there good notes left behind. Instead of jumping in and making the changes I need, I’m spending hours and hours just trying to decipher what these functions are supposed to do!

I’ve run into this a few times before and it’s taught me a very valuable lesson: Can somebody who has never seen your project before look at your code and be able to understand the general idea of what it does? If you have to think about that when coding, then the answer is probably no.

Let me give you an example. I am currently updating some maps that overlay location markers. These maps were created about 5 years ago by a previous developer. I was hoping that I could jump in, add a few items, and jump out, all preferably within a day’s work. However, now I’m looking at the coding and I have no idea how it’s working together. There are variables named “s” and “u”. Oh, thank you for that descriptive name so I know what that does!!

Then, the previous developer used those same letters to preface certain functions. For example, “u_pts()”. I already don’t know what “u” stands for, so I definitely won’t know what this function does. It’s mildly infuriating.

This is where I go back to me questioning if another developer can understand your code. I should be able to walk into a project and spend some time figuring out what the code does without having to spend time figuring out what a variable is named for. Instead of “s”, put “species_name” or something specific. Sure, it takes one extra second to type out, but it will help tremendously. That goes along with functions too. Name a function in a way that describes what it does. Also, PLEASE leave notes above the function to describe, in detail, what it does, what it changes (if anything), and what the expected output should be.

These should be common practices among programmers. I know many professors who enforce this readability, as they should! It was taught to me in my very first programming class years ago. Always give your functions and variables names that mean something.

*I’ll give you one pass: using “i” instead of “index” in a small for loop. That one I’ll let slide (though you could just say index…).

Have you ever heard of PTP? Most people haven’t, unless you’re an engineer dealing specifically with timing. For example, broadcast engineers will setup their network to run PTP so that all their cameras and systems will be synchronized. It’s an incredibly important, say mandatory, step in the core of a broadcast operation.

PTP stands for Precision Time Protocol. It runs either through ethernet or IP-based ports. Simply put, it’s a protocol that will adjust the internal time of a machine so that it matches a “Grand Master” time source. It accounts for simple differences in time on each machine, as well as delay in sending signals over the network.

Let me give you an example. Say we have 3 broadcast cameras. Each are sending back video to the broadcast unit’s core. Some of those internal times may be slightly off. If they are too far off (in nanoseconds), when a director switches between cameras, the internal system has to switch to a different source. If those times are out of sync, then a black hole appears as the system switches. If they are in sync, then it is seamless. Remember old tube tv’s in the 80’s? You’d switch to a different channel, it would take a second and go black in-between changing channels. That’s what we’re trying to avoid with PTP.

The “rules” for PTP are documented in IEEE 1588. The way PTP works is basically a 3 step process. This is a very generalized view of it, there are a lot of other items that can be added and/or changed.

First, the Grand Master (GM) sends a sync message to a Slave machine (these terms are changing in new documentation to Leader and Follower, but for current documentation I will stay with the same terminology). The GM notes the time it sends this sync message. The Slave receives the message and records the time. (Sometimes, the Grand Master will send a follow-up message as well, depending on PTP configuration).

Second, the Slave sends a delay request to the GM. Basically, it is saying “Hey GM, I received your time message at this time”.

Lastly, the GM receives that delay request from the Slave. It knows when it first sent the sync message and compares that to what the Slave is sending as the time it received that sync message. It calculates the difference in time and sends that difference as a delay response to the Slave. The Slave gets that message and adjusts it’s clocks based on that delay. Thus, the two clocks become synced, including delay in network traffic.

This process happens over and over and over again. The machines at my work do this about 8 times a second, for example.

Upgrades are currently still in development. PTP is an open source library, so anybody interested can clone and use it. It’s an incredibly accurate process that’s revolutionized precision timing.

Having been in the workforce for 15 years now, I can tell you, without a doubt, different backgrounds are important. No, not different CSS color backgrounds (I prefer a nice navy blue in case you’re wondering), but diverse employee backgrounds.

Let me tell you about my current work, since that’s pretty much all I’ve written about so far anyways. I was a hire that was slightly off center. That is, I didn’t have the background they were looking for specifically. They wanted somebody who loves Linux and creating software that runs with very low level stuff, aka hardware. I had … 0 experience with that.

I applied anyways though because the company makes rack equipment for broadcasting companies. I had worked in broadcasting for a decade, so it seemed like the fit may be there, but from a different angle than they originally wanted.

Sure, it took a while longer than expected when training me, and perhaps I’m going down a road of software engineering that is different than what they hired for, but it’s been a great fit for both of us. They love asking questions about how a user would use this product.

None of the engineers on my team have worked in broadcasting. They built products they think broadcast professionals would want and use. Many times, they’ll throw in a bunch of functionality that simply isn’t going to be used, or stuff that may be used, but not in the way they’re thinking. That’s one of the reasons they love asking me questions.

For example, one of the teams builds a product that shows waveform and vector scopes (among many other things). One of the options was to adjust “stuff” to match what broadcast video is putting out. The item has great functionality, IF you have time to play with it. Broadcast engineers may have the time when setting this up, but they don’t look at it much after that. Primarily broadcast directors would use this in everyday operation. That’s the position I worked in. I was able to talk with the team about how I used items like this. While all the functionality is great, I don’t look at any of it while directing a broadcast. I need two or three specific things that are quick and easy to get to, that’s all I need. We were able to put in some design comments for the next generation of that product, and that felt good being about to contribute to the product based solely on my background.

I wish our teams had more diverse backgrounds. People coming in from a complete outsiders perspective give the best suggestions, because it’s all new to them. I highly encourage managers to develop diverse teams and to not be afraid of bringing in talent with backgrounds that may not seem like a match at first. It’s worked for my team already!