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.