Take your code from Zero to Hero with 5 easy tips!

https://xkcd.com/1513/

Intro

We’ve all had experience when we either needed to share our code with someone else or go back and figure it out ourselves and realized that it was bit of a clumsy mess. This is part of the process of learning, but there are 5 things you can start doing today that can improve your project and code quality significantly with minimal invested effort.

Table of Contents:

1. Project Folder Structure
2. VSCode Formatters
3. Using npm, venv or virtualvenv, etc
4. Wrapping Third-party Packages
5. Don’t Indent Too Much

1. Project Folder Structure

Choosing a good structure for your project can determine how often you come back to improve it. When the structure makes sense and provides quick access to the portion of code you are interested in, you are much more likely to make improvements because you understand the structure without having to spend time re-learning the how it is structured.

In my opinion there is no one right answer for how this should be done. We all have different preferences, the most important thing is consistency throughout.

As an example, if you’re starting a project with ReactJs and you aren’t familiar with best practices then I would suggest Googling “Reactjs project structure examples”. You’ll find handfuls of examples on Github showing different ways to structure and organize projects. It’s worth taking a quick look and picking one that makes sense for your use case.

If you want to invent your own structure, great! Here are some tips:

1. Have a src/ folder — all of the code you write should go in here
2. The only files at the top level should be ones relevant to the whole project, like a build script or Dockerfile, for example
3. Try to think in general terms when creating subdirectories inside the src/ folder
4. Make your structure work for you — if an import or include statement feels hacky, that could be a sign you need to restructure

2. VSCode Formatters

I had serious doubts about how useful VSCode would be with all the bells and whistles it reportedly had. I had been using the Atom IDE for awhile and was pretty happy with it, but decided I should at least try VSCode so I could experience the other side. When I finally tried it out I was surprised how much I liked it right away. The main features I love are: 1) the built in command line and 2) the code formatters. It does take a little bit of work to get them configured right, but once that is take care of it really starts to pay dividends. I always enable the “Format on Save” option, so that my code will be formatted and checked for errors simply by typing Ctrl+S.

If your code is cleaner, you’ll just hate it less and improve it more. Not to mention you’ll be more proud of it because it looks nice and consistent. Spend the time to get a formatter installed and configured. Your future self and your colleagues will thank you for it.

3. Using npm, venv or virtualvenv, etc

This can’t be stressed enough. Using a package manager specific to your language of choice offers a host of advantages when starting new projects and improving on older ones. The best part for me personally is knowing that all the dependencies are all contained within the project and I won’t need to do any hacky things to get it working on a different machine. Before I began using npmor venv consistently, deploying code to the production environments was an absolute mess and never really worked the way I intended. Installing individual dependencies by hand almost always results in a version mismatch and is a pain to debug.

To get started with Node.js and npm try the following:

First, be sure to install Node and npm or check it installed correctly:

node --version
npm --version

If these commands return a Node.js and npm version number, continue to the next section:

mkdir myNewProject
cd myNewProject
npm init

After running npm init the terminal will prompt you for some project details, like this:

> npm init
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.
See `npm help init` for definitive documentation on these fields
and exactly what they do.
Use `npm install <pkg>` afterwards to install a package and
save it as a dependency in the package.json file.
Press ^C at any time to quit.
package name: (mynewproject)
version: (1.0.0)
description: A cool, node project
entry point: (index.js)
test command:
git repository:
keywords:
author: Gideon Stowell
license: (ISC)
About to write to /home/user1/myNewProject/package.json:
{
"name": "mynewproject",
"version": "1.0.0",
"description": "A cool, node project",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "Gideon Stowell",
"license": "ISC"
}
Is this OK? (yes)

You can change the name, description, git repository url or other settings as it prompts you. Don’t worry, all these settings can be changed later if you change your mind. Sticking with the defaults for some items can be a good way to start.

You should see a new file in your project folder called package.json, this is the file that contains all your project information, including dependencies.

We can add dependencies really quickly using npm. While still in our project folder we run:

npm install express --save

After a few moments you will see the package has been downloaded.

Now if you open the package.json file you should see a new section:

{
  "name": "mynewproject",
  "version": "1.0.0",
  "description": "A cool, node project",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Gideon Stowell",
  "license": "ISC",
  "dependencies": {      # This was added by the npm install command
    "express": "^4.17.1"
  }
}

This section will fill up with all your dependencies as you continue to install them.

One last tip, when you move your code to another machine for testing, staging or production you don’t need to install these dependencies by hand. Simply run npm install in the project folder and npm will detect the dependencies in your package.json and install them all. This is very helpful when working with teams too!

Here’s a guide on getting started with venv!

4 . Wrapping Third-party packages

This is a slightly more advanced technique. Wrapping a third-party package protects you from a headache if the package changes or you choose a different package all-together. When you minimize and localize the direct invocations of a third-party package, you minimize and localize the future changes you would have to make related to that package.

Here is a simple made-up example:

I want to the use a third-party package called file-mover that has two main operations: copy and remove.

The best way to include this in my code could be to create separate file called file-mover-wrapper.js like so:

const filemover = require('file-mover')
const delete (obj) => {
    filemover.remove(obj)
}
const copy (obj, dest) => {
    filemover.copy(obj, dest)
}
module.exports = {copy, delete};

Now I can include the these wrapper functions throughout my code and use the operations supplied by the file-mover package. Now this might seem redundant because my wrapper functions just invoke these operations directly. But watch what happens when I want to extend the capabilities of the file-mover package:

const filemover = require('file-mover')
const delete (obj) => {
    filemover.remove(obj)
}
const copy (obj, dest) => {
    filemover.copy(obj, dest)
}
const move (obj, dest) => {       #This method is new
    copy(obj, dest)
    delete(obj)
}
module.exports = {copy, move, delete};

As you can see the I am now able to easily add new functionalities to the wrapper without changing much in my code directly. I can simply add an invocation of the move method and that is done.

Also, consider if I decide the file-mover package doesn’t have a feature I want, so I pick a new package to use. All I have to do is change the invocations of the file-mover package in my wrapper file and replace with the new package. No need to hunt through multiple file to find all the direct invocations there. This results in cleaner code and quicker modification throughout the life-cycle of the product and becomes more and more helpful when the third-party packages have more and more methods.

5. Don’t Indent Too Much

I find that if I have indented 3 or more times in any given function, I have probably created some complex logic and need to refactor. By keeping your indentation to 1 or 2 levels, the possibility of highly complex logic decreases significantly. Hopefully, the reason for this is self-explanatory.

Fixing this can be as easy as breaking out the deeper logic into smaller functions and routines that will also follow this principle of having fewer indents.

Conclusion

Bonus tip for those who made it this far: Quality code is a somewhat subjective thing. If it is easy for you and your team (which sometimes is just yourself) to understand then it is likely good enough. Don’t get caught up in trying to follow every best practice ever invented at the cost of never getting anything done.

Striving for good code quality is hard work, but worth the effort because you will standout against your peers and learn more. Organization in programming is the difference between a good programmer and great one.

If you found this help or have some other tips I should’ve included, let me know!