coding guides, API's and how-to's

Coding can be a very personal thing many a time. Some people like camel casing, some like Pascal casing. Some people like to add the curly brace to the end of the line, some like to add it to the beginning of the next. To each their own in that regard. But here are 3 quick tips to help improve your code in the long run.

This is intended for those that like to code alot, and have thousands of lines to maintain and stare at on a daily basis. This could also be very beneficial to those that work on teams, and so your code is not really your code.

1. Add dates to your code

Start dating your code. It may seem bright and shiny right now and you may not dream of changing a thing next week. But in 3 months, you are going to insult the name of the person who wrote this dreadful function. Dating your code allows you to see just how 'outdated' it is. I personally have functions in my code from 2011. Needless to say I rarely touch them. But some of these need to be deleted. They are using old outdated libraries and some may be deprecated at this point. Do they even work? It's hard to say.

However, if I had not dated them, I would just assume that they were as fresh as a daisy and leave them be. Lucky for me I got into the practice of dating my code several years ago at a certain job where projects got created and dropped at the drop of a hat. And so I wanted a better way to keep track of what I was doing on a weekly basis. And it has been a practice that I've kept up with since then.

The biggest benefit that I get from this is definitely being able to question the validity of my code as I mentioned above. Something that's 5 years old, definitely needs to be looked at one more time, even if just to be safe. And eventually, yes, it will need to be deleted.

// 11.19.2018

2. Comment your code...alot

And I mean alot. Don't just do your typical:

// this is important..don't forget

But add meaningful comments that you yourself will thank you for later on down the line. Notice that these first 2 tips have much to do with reading your own code. And that's because reading your own code is one of the hardest things to get used to and to get good at when coding. Your best code today, is your worst code tomorrow. And it will be your worst work day in about 2-3 years.

A few important things that you can comment are:

  • Date code was added (mentioned above)
  • Who wrote the code (your initials)
  • Business logic that isn't clear ("Sam asked for this bizarre feature")
  • Any (and I mean any) quirk or oddity that you had to do to make it work

When working with teams of more than 2, I normally initial my code, just so that somebody else can identify what code to touch and which to ask about. Business logic is something that is super dynamic and constantly changing. Which means your comments will also be doing much of the same. If you have to "subtract 10% off the total, but only during the 2nd Saturday in March", then that is core logic that needs to be identified.

And lastly, anything that you had to Google is always good to have as a reference. If you are using a complex formula, that you borrowed from some GitHub page, then link to the GitHub page.

While much of this is designed to help you read your own code later on, it's also nice for the next generation of programmers that will take over your work at some point in time. A project that is cryptic in nature is almost impossible to update, particularly if it's a large scale application with active users. Any little change could cause issues and essentially cause un-needed stress to both developers and project managers and companies as whole.

3. Delete your unused code

And last but not least, and quite possibly the hardest habit to break, delete your old and unused code. You won't use it again, believe me. It became unused for a reason and leaving it behind in the case that you will need to come back to it next week, will only make it harder and harder the more abandoned code you leave behind.

If you are using source control, then you do not have to worry about losing your precious logic. It will be there, if and when you ever decide to revisit it. And if it's something that is important or complex, then maybe putting that code into a separate location might be beneficial for it to not clutter up the namespaces or to confuse people as to whether that thousand link function is indeed in use.

A good way to begin the process is to comment your unused code with something like "unused" or "for deletion", to start. At least this way you won't be confusing yourself or anyone else with phantom code. There should be time allowed in your schedule for code refactoring, essentially where you clean up your code. This is a great time to go in and to remove any "for deletion" items.

Having just too much code in general makes it a tedious task sometimes to go in and to make quick changes, even if you aren't touching most of the code. But loading up a 5,000 line file, full of 'auto-suggestions' and 'warning' signs isn't conducive to a good work setup.

The common theme in this list is maintenance. Knowing what you wrote, why you wrote, who wrote it and being able to remove it once it is no longer needed. And that's because you are going to write alot of code in your career. I've safely written over a million lines of code in my time. And while that sounds like a high number, I can safely say that I've written 10,000 line JavaScript programs at past jobs, and that's for a single one off projects.

Eventually, this gets almost impossible to keep track of, which is why I offer you these tips. So that the future you will thank you at some future point. If you have any tips of your own, please share down below in the comments section as sharing is caring.

Walter Guevara

Walter G. is a software engineer with over 10 years of professional experience. When he isn't blogging or being a CTO he enjoys coding randomly complex things that he hopes many people will get a chance to use one day.


No comments posted yet

Latest Posts

Add a comment

Send me your weekly newsletter filled with awesome ideas
Post comment