What happens when a TTT employee dies

Confessions of a Developer: Documentation and coding
fb twitter linkedin
link
Copied!

We’d be okay. Well maybe not emotionally, but our code would be.

As a Developer, a good question to always be asking yourself is, “if I had to be taken off a project abruptly, do I code in a way that makes it easy for the next person?.”

Developers often like to keep things to themselves, especially newer or inexperienced ones. This is something I’ve witnessed while teaching new developers how to code.

Coding is not a one person job despite what it may look like from the outside. I can’t stress how critical collaboration is, not only when working in a team environment, but for self improvement as well. Sometimes the best way to learn is from watching someone else, and getting them to watch you.

Below are some suggestions that I would consider standard practices every developer should follow. I’ve seen some interesting things from my time as a mentor, instructor, and even in some professional settings with code that’s been handed to us from a third party.

General setup and updates

Google drive

This first one is a doozy. Whether it’s Google Drive, SharePoint by Microsoft, Dropbox or some other similar service, uploading your files to the cloud where everything is safely stored and backed up is a great place to start. Use these platforms for any files that are not meant for your code repository. I use Google Drive mostly, but any of those platforms will do. 

Anything that is saved on the harddrive of your computer is at risk of getting deleted. It also means that no one else has access to it but you. There might also be multiple versions of the same file at different stages causing confusion. To keep things simple and accessible, store your stuff on some sort of cloud based file sharing platform.

READMEs

READMEs should tell someone exactly how to run your code, and how to set up your IDE (Integrated Development Environment).

I’ve run into a situation in the past where I spent way longer than needed to figure out why the code wasn’t running. In the end, I discovered it was because the code would only run on a certain version of Xcode after spending some time doing detective work, time that could’ve been spent doing something more productive. Something like that is exactly the kind of information that would’ve been helpful to put in a README.

You don’t need to overload the README with unnecessary information, but you should always include the version number of anything you’re using, and even what libraries you’ve used (with links attached).

Libraries

So the good news is that there are millions upon millions of libraries available. If there’s some kind of obscure feature you need to implement, (it’s kind of like how Apple put it in their iPhone 3g commercial “There’s an app for that”), or in this case there’s a library for it.

The flip side is that a huge chunk of those libraries are obscure, and have not been battle tested. The thing with libraries is that, although they may be very convenient, they need to be thoroughly researched before you plop it in with the rest of your code.

I like to stick with libraries that are widely used for a couple of reasons:

    • They’re more likely to be updated frequently
    • If your team members have also used the same library, they don’t need to learn it from scratch.
  • Chances of it being incompatible or “stale” are lower.

Coding standards

Architecture

This next point I cannot stress enough. Always take the time to think about architecture before writing any code. Measure twice, cut once as they say. Or (think twice, code once if you’re a developer).

This is something I tell my students all the time. I’ve seen students and more junior developers jump into a project without proper planning. They would end up having to start their project again from scratch because they didn’t take the time to think about the structure. This might not be as big of a deal in class, but translate that into a business, and you’re losing a ton of time and money.

That being said, don’t over architect either. I know I just told you to take the time to think about it, but the opposite is also true. There’s a point at which the benefits from the improvements made are so minimal that the cost of the time spent over-architecting ends up outweighing the benefits.

As with anything, there’s a balance you need to strike. Spend the time to figure out how to setup the proper architecture, and then start executing it before you reach a point of diminishing returns. A great way to save time on planning is to ask another developer to look at your setup, which brings us to our next point… code reviews. These segways are well thought out folks.

Code reviews

Always get a second opinion, even when you’re the one with more experience. You’d be surprised at what a fresh pair of eyes could do. You would never write a book and then publish it without getting someone to proofread or edit it. The same goes for writing code.

Reusable & adaptable code

One way to make your code reusable and adaptable is by keeping everything small. Keeping your code in short snippets allows someone who is new to the project to see isolated code and be able to change it without affecting other pieces.

It’s also a good idea to create reusable components. If you know that a certain feature is going to be repeated a lot throughout the app, you can template it. Anytime you need to make an update, you’d only have to change it in once place instead of doing it separately. This will save you time if there are any major UI updates.

Commenting

Commenting is an art. I’m going to just come out and declare that.

We’ve all heard of the argument that “good code is self documenting”. I think this is a phrase that gets misinterpreted a lot. This phrase is saying that you shouldn’t be adding unnecessary comments when it’s something that can be mitigated by good code. It does not mean that there’s never a need for comments, or that it’s a waste of time.

Comments shouldn’t just reiterate what is written in your code, or be clarifying bad code. It should be communicating the intent of the code, giving context that you wouldn’t otherwise pick up on. You could write the most beautiful, perfect piece of code in the world and it still wouldn’t tell me exactly what its purpose is. And believe me when I say that context matters.
When misunderstandings occur or someone misinterprets your code, and trust me it happens, they might modify it in a way that causes problems because they didn’t fully grasp the purpose of the code. The more of these misunderstandings we can prevent, the more time we save, the easier we make our other fellow developers’ lives. You’re going to find lots of people calling commenting a waste of time, and to that I say, if they have time to complain about commenting, they have time to put some damn comments into their code :).

Software advances

We operate in the tech industry, and anytime we’re not actively learning about new features, standards, or updates on frameworks, we’re falling behind. Sometimes when we’re working by ourselves or working remotely, we can fall into the trap of building the same view multiple times in the same way because we’ve done it before. Every time we’re about to do this, we should check if there are new ways of building something before following a mold.

Even over the span of months there could be a new standard. This is evident with the latest releases of Swift. If you’re a Web Developer who doesn’t know what React is at this point, I don’t know how to help you. Part of working in tech is always staying ahead of the curve.

In the end…

As Developers, we need to be making life simple for one another. This brings me back to my original point that “coding is not a one person job”.

When I come across well written, well documented code, I honestly take a second to stop and appreciate the beauty and all the effort that developer has put into writing it. On the flip side, I like to think that maybe, just maybe someone’s out there appreciating some of the code I’ve written.

Alright maybe that’s asking too much, but at least I can sleep at night knowing that if someone is out there cursing my name, it won’t be because of my code.

Oh and if I were to die tomorrow trying to saving that puppy from getting hit by the car, my team would get along just fine…..albeit hopefully a little sad.


To learn more about Mitch, read about him in our “Meet Our Totems” series.

Recent posts