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.

Beta Testing is Important

Remember the days when new software was released, but the only way to get it was by purchasing a disc from the company, then installing it yourself? (Goes right along with those fun AOL tones we used to have!)

When a company released a new software version “back in the day”, there was a lot more overhead. They had to really beta test their software update to make sure it all runs as it should. If there’s an error, then the customer gets mad. There wasn’t an easy way to push out a new software version just to fix that error.

Nowadays, companies will add some features and fix some errors, then do (if at all) little beta testing on those features and push them out over the internet. If there’s an error, it’s annoying for the customer, but not a big deal, as they know an update will come soon to fix it. It’s good in that customers can rely on these routine updates to fix bugs. At the same time, customers have become desensitized to these bugs. It’s just become part of some software, and personally, I think that sucks.

Take my friend, for example. His job revolves around using a specific software for broadcast graphics. He routinely finds bugs in their software. Unlike, say, a video game where an error can usually be overlooked, these bugs in software will crash programs and make his edits unreliable to his clients, because the software he needs has bugs. To make things worse, when they push out updates weekly, one bug will be fixed, but that fix will then crash other parts of the program. He quite literally has to save “good” versions of their software until he can find another one that seems to work well.

Software shouldn’t be this way. As much as I love the convenience of having routine updates available at our fingertips whenever we like, I do miss the days of software being mailed as a CD. I can be confident that the developers beta tested their software over and over again. I wish tech companies could keep this beta testing mentality, but merge it with today’s convenience.

One can dream!

Why Software Usability Heuristics are Important

One aspect of software engineering I like is the User Interface. I think a product is only as good as the UI. If a user can’t figure it out, or the UI doesn’t touch functionality built into the code, then the product becomes less useful. Personally, I like simplicity for users, with the option of diving deeper into a UI if a user is more advanced or interested in it.

I would say I’m a more advance software user. I am always that person helping family members and friends setup software or edit software they’re using. I enjoy looking more into all the settings of a website so I can use it to the best of my abilities.

One thing that is important to me is the idea of being able to do something that the application “seems” like it should do. For example, if I’m using the github desktop app, I would expect it to be able to connect to my github account, link local repos with a master repo, review pull requests, etc. Anything I need for this type of project, I would expect that app to be able to do.

I’m a fairly new user of Slack. Before, I’ve never really had a need to use it, until I started working on my capstone project. The sponsor I am working with uses slack to communicate. Sounds good to me, I’ll join.

So far, so good. Up until I decided to venture off and build my own workspace, as they call it. Just to test it out and see what it could do. After playing around with it, I was ready to delete it. I’m using it through the slack app on my phone. I’m searching, and searching and searching some more, but I can’t find anything about workspace settings. This is something that I “feel” should be part of the app. Can I only create workspaces, but not delete them?!? That seems ridiculous.

Turn to Google. I look up how to delete a workspace. Finally find directions, but you have to do it through the Slack desktop app. Ok, weird, but sure. Download the app for my laptop. Finally get to the admin settings. Which, (face palm), takes me to a their website! Why did their own directions tell me to download the app, just to take me back to the same website??

This, to me, seems like a bad setup. The phone app should at least have some of the options on it to delete a workspace, and if not, have a link to that website I ended up at. Not directions to extra steps in the middle!

Rant over.

Anyways, my point is, an app should be able to do what you think it should. I know that’s a general statement, but I think it rings true. If you build something, make it all inclusive across all it’s apps, and if you can’t, at least try to cut down unnecessary steps. Keep it simple.

Add Some CSS to Your Workplace

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!

The Dreaded Technical Interview

What’s the worst thing about looking for a job in software engineering? In my opinion, that would be the technical interview.

It’s easy enough to talk about projects you’ve worked on or how you would be a good addition to the company, but it’s another thing to be able to show off coding skills on the spot, especially for a junior engineer.

I’ve completed (completed may be a strong word) several technical interviews. Each one a little different than the last. The worst was for a gaming company in town. I had twenty minutes to code, using C++, a problem they gave me. While normally this would be no big deal, my heart started racing when I knew I only had the 20 minutes AND two people on the zoom call were watching my every keystroke. That was horrible. Let’s just say, I did not hear back after that.

Other technical interviews are a little less stress based. I applied for a job at Amazon and went through multiple rounds of technical interviews. These were all timed as well, but didn’t have somebody watching me. It also consisted of multiple smaller exercises, and they mainly wanted to see what thoughts I could apply to these problems, if I didn’t finish it. I did well, was invited to do some in-person interviews, but ended up not pursuing any further after that because of a different job opportunity.

I think my favorite (favorite, yet again perhaps a strong word) technical interview was for my current company. There was no coding specifically, the hiring manager even mentioned that he can look at my portfolio to figure out my coding ability. We talked concepts. The manger provided different scenarios that fictional users may encounter. He wanted to see how I approached it from a high-level view. For example, one scenario was a new parking garage keeping track of cars that come in and go. The prompt was specifically vague, in order to see where I’d go with it. They’re looking to see if people create user stories, ask for more details, see prompt for what needs to be fixed, find out what external pressures there are, etc. The idea was to see how I would handle a new project and if I could ask the right questions while setting up something that the user actually wants, not just what the user says they want.

I liked this idea a lot more than the usual “here’s a problem, code it to make it work”. I think giving a more high-level view of a problem and seeing how somebody would handle it is more of an insight to a candidate than seeing if they can make a small problem work under pressure.

Let’s just say, I’m happy to be working for that hiring manager now. He clearly appreciates different views that his team members bring to the table. It creates an interestingly diverse team all working towards the same goal.

I got the job! Now what?

Have you ever started a new job and had no idea where to begin? I’ve had that feeling, 8 times specifically since I first graduated college in 2010. Sometimes I can blend into the position and soon run with it. Other times I feel lost for months. It may be worrisome, but let me tell you, it always gets easier.

I’ve worked in the local news industry for 12 years, starting as a photographer’s intern, later trying out producing, then finding my niche in broadcast directing.

Remember this scene from Star Wars?

Yeah? Well that “control board” is called a switcher. We use it (or automate as of recent) for directing local news. When I first became a director, that board was intimidating! There’s buttons, there’s menus, there’s external devices. There’s anything and everything Grand Moff Tarkin would want when blowing up planets. As a new director, I thought I’d never figure it out. Things take time though, and sure enough, I became an expert. So much so that I was teaching others the intricacies of the switcher just a couple years later.

Fast forward to today. I officially switched careers and landed my first software engineering job with a company that makes broadcast equipment (how fortuitous!). The first two weeks I spent just playing around with the equipment, not even looking at code. That was challenging enough. Then they gave me the keys to the (source code) kingdom. There’s millions of lines of code, most of it legacy. By legacy, I mean there are chunks of it they still use that are dated in the ’90’s.

I’ve been here nearly 5 months, and I’ve barely scratched the surface. Many times I still feel overwhelmed. I have to remember from my experience with new jobs though, it gets better. It’ll take some time to get used to developing software and the intricacies it entails.

If I can provide anybody in similar situations or for many students looking for their first job in a new industry, this is what I’d say: Always ask questions! Find those people at your new job you trust and pick their brain. You’d be surprised how many people like to share their knowledge with junior developers. Embrace code reviews and do your best evaluating pull requests. Be open to trying new technologies and always push to do things outside of your comfort zone. Most likely, we won’t be in this same job 5 years from now. Develop skills in the real world that are useful. Don’t lump yourself into coding in just one language.

Sometimes new jobs are fun, most of the time they are terrifying. I definitely get a sense of imposter syndrome with some positions. Always remember though, they hired you for a reason!