Monthly Archives: February 2022

Please Name Your Functions!!

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…).

Timing precision with PTP

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.

https://en.wikipedia.org/wiki/Precision_Time_Protocol

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.

Why Learning the Command Line is Critical

It’s can be deemed the most useful and necessary tool out there for any developer, yet for green engineers, it can an anxiety inducing. I’m talking about the command line, aka terminal, shell, command prompt, etc… While it’s not some fancy UI tool, it is a something I can (nearly) guarantee you’ll use in your career.

My first class, years and years ago, in computer science was Linux 101. A good chunk of the class was focused on interacting with the Linux kernel through the command line. Of course, at the time I asked myself “I’ve got FileZilla to move items around, why would I use the command line? ” Quickly I learned though that’s its functionality is more than meets the eye. It is a shell that can control very complex operations within your system, that other areas cannot.

As a software engineer, I use the command line daily. It’s quick and efficient. It uses much less CPU time as other interfaces. I’m not doing anything too complex, but it sure makes things easier once you know the commands to use! For example, I want to securely copy a .tar file from my local computer to a different system on my network. Sure, I can open up FileZilla, ssh into the other computer, make sure my credentials work, wait for it to load, find my local file and drag and drop it on the remote computer. Or I can run a “scp <filename> <target_computer> command from terminal, and it transfers that .tar file quickly and easily.

Sometimes, it can help when trying to get access to a remote computer. Just the other day, I was using VSCode’s Remote Explorer extension to SSH into a server. It kept giving me an access error and I couldn’t figure it out. After about ten minutes, I gave up and just used the command line “ssh <username>@<server_name)” and just like that I was in. It took less than 30 seconds.

The advantages go on. It’s easy to handle repetitive tasks one after the other. It uses less memory. It doesn’t require Windows or a Mac OS. You can do most anything from it with fewer resources!

Need to edit one line in a file you’ve already transferred to a remote computer? Use vi(m) through the command line! I read an article the other day comparing editors. Vim uses one process, 2.4MB and one thread, while VSCode uses six processes, 356.3MB and 134 threads. You can see that using vim saves bunch of processing time and space.

Let’s not forget, many cloud services are operated through the command line. Most projects that require an immense amount of computing resources are run through the cloud, and interaction with those services are through command line interfaces.

There’s plenty of reasons why learning the command line is important for any engineer. You can develop faster. It is very intimidating at first, but after a while you’ll find it’s much simpler. You enter a command. It either does what you want or it tells you what’s wrong. Plain and simple.