Programming best-practices for those starting out

Published in

MacLaurin Group

8 min readAug 10, 2019

We get asked a whole manner of questions in and around software development at MacLaurin Group, but a few questions keep recurring from those entering the field and looking to succeed.

Today’s question: What are the best practices for programmers starting out?

Ignoring language-specific tools or paradigms, here are some of the most basic things and concepts a fledgling programmer should keep in mind.

I haven’t listed things in any particular order, they’re all equally important ;)

Short functions/procedures

A function should be as long as it has to be and no longer. When you think it’s as short as it should be… You can usually pair it down a little bit further!

It takes experience to learn how to do it, and it can seem odd for a beginner when you see a file with lots of 5–10 line functions, and only a few long ones.

It’s a common pattern to have lots of small specialty functions that does just one thing, and then a few functions that interact with other classes, or are called from the outside.

For example, you might have a user class with a public function called validateUser() which calls many private validation and returns a simple boolean or error map to its caller.

When your function hits 15–20 lines or so, it’s time to evaluate if it should be broken out into several related-but-specialized functions. There’s no hard rule here! Sometimes it should and sometimes it shouldn’t, but as a beginner it’s better to err on the side of splitting it out to get into the habit.

Sensible and descriptive function and variable names

Good variables names tell the programmer useful information about what it’s for, and in some languages what type of variable it is.

In those case it’s common to prefix with a letter, for example bUserHasAccess for Boolean, or aUserPosts for Array, and so on.

The only one I let people get away with in code reviews, are loops and the variable i , as in for(i=0; i<=length(users); i++) simply because it’s a super common pattern, it’s short for index , and it’s only used to indicate position in an array.

Not only is it easier to read and understand code with good names, it also helps when IDEs use auto-suggest, because instead of an endless list of “id” you know that you need “corporateId” and not one of the other ones.

Example:

// Bad variable name
var a=4;// Better
var userId=4;// Best
var studentUserId=4;

And for functions, it’s the same thing really

// Bad function and parameter names
function validate(a, b){}// Good
function validateStringRegex(stringValue, regexPattern) {}

Plenty of comments

But please, make them useful comments!

// Bad developer, don't do this
// Loop the values
for(a=0; a < 100; a++){}// Good
// Sort users into arrays based on age
for(index=0; index < length(userArray); index++){}

Don’t just repeat what the code already tells the reader, tell them what or how you’re doing it, at a higher level.

/*
   This class deals with Twilio messages as it relates to a specific
   enterprise client and their validations.   Most are the same but a few clients have variations in their 
   validators accounted for by using standardValidator() or
   <client id>Validator(), see documentation entry someurl.com/docs 
   for details
*/

Function comments follow the same concept.

// Bad comment
// This function validates usernames
function validate(username){}// Good
// Validates a username for char count, UPPER lowercase, length, and that it doesn't contain parts of their email or username
function validateUsername(username){}

I make mistakes too.

I’m writing a library and just went back to a piece of code, to continue where I left off early yesterday. It took more than a few seconds to remember what _closeText was!

Here’s the function signature

function alert(_message, _closeText){}

It made sense when I knocked it out yesterday but looking at it now, it’s obviously not clear enough. The new version looks like this:

function alert(_modalBodyText, _closeButtonText){}

Avoid “clever” code

It can be fun to figure out how to do something “cleverly” to save a few lines of code or gain a fraction of speed improvement.

But, BUT, unless you really need that extra space or the little bit of speed, you’re actually hurting yourself and your team by increasing the cognitive load for everyone reading your code in the future.

Cognitive load in this case is more or less “How much time and mental effort is required to process and understand what I’m reading”

That includes weird ternary statements, mixing positive and negative checks in one statement, really long one-liners, etc.

It’s better to have multiple lines of very clear code that everyone on the team can understand at a glance, than a single line that takes everyone effort to even read.

Classes/Units are your friend

Classes, units, whatever you call them, they’re the puzzle pieces you create which together make up the whole project.

Split your code into logical pieces, it makes your code easier to maintain and extend, and much easier to work with for someone new to your code.

Splitting it up also makes it easier to work on the same code base as a team. You’re less likely to step on each others toes (Merge-hell) or make changes that break someone else’s code.

A simple example is a user class and some related functionality.

Let’s say you also have email, phone, and address validations.

You don’t put those in the user class because they’re not related to the user itself but its data, and you want to use the validation code in places other than the user class.

So you might have a single class for validations, or even better, have a class for each type of validation which takes whatever options it needs and does its thing without needing to know anything about where it’s being used.

It’s better to have several files/classes that are clearly defined rather than a few big files that cover too much.

Don’t prematurely optimize, but don’t ignore it

This is more of an experience thing but still important to mention.

Speed matters, but if you’re spending half a day to gain 50ms you’re either wasting time, you really need that 50ms, or you’re just having fun.

The key is to spend time where it’s most valuable, remember that your job isn’t writing code, it’s solving problems.

It’s basic prioritization, or triage, you figure out what the most impactful work is and start there.

Ask for help

We all get stuck and bang our heads on the desk sometimes. Software development isn’t easy (anyone telling you it is, is either selling you something or is lying to make you feel better).

It’s simple however, in the same way as chess!

Chess is easy to get started with, but oh boy there’s a world of pain when you go up against a skilled opponent if you are not. It’s not only okay to ask for help, it’s required!

Just follow a few simple rules and you’ll be fine:

Try to solve the problem in various ways yourself
When asking for help, let them know what you’ve tried and how long you’ve tried

No one wants to waste time looking things up, digging through their old code, or write elaborate answers to simple questions just because you gave up after 10 minutes.

But if you do

Spend time trying things
Do your research
And you’re still stuck

Then people are generally more than happy to help you out.

Mind you, most of us won’t just give you an answer, but a way for you to figure out the problem for yourself.

In my current team we have a simple rule; If you’re stuck on the same problem for 20 minutes, ask someone for help.

This is a team of experienced experts, so the problems that crop up aren’t generally searchable. The collected experience of the team can break through the problems much faster than a single developer typing away for hours.

Help others

On the same token, you should help others where you can. It’s okay if you’re not an experienced programmer, you know stuff that others don’t, share the knowledge!

Most people are not your competition, it won’t hurt you one bit to help someone else out. Pay forward all the help you get as you learn :)

Write lots of code

The most important thing though, is to write lots of code. Actually, not just writing code, but writing your own code!

Following a guide or tutorial is helpful when learning the core concepts but isn’t anywhere near getting you to the point of learning whatever it is you’re studying.

A simple progression is