5 Software Engineering Best Practices

In this article, I’ll go over some best practices of software engineering you can use today to be a better software engineer. Adopting these techniques will may you a better developer and prepare you to write production-level code. These techniques will make your code more readable and maintainable.

• Write clean and modular code

• Write efficient code

• Refactor your code

• Add meaningful documentation

• Use version control

Write Clean and Modular Code

What is clean and modular code? It is a production-level code that meets the following criteria.

• PRODUCTION CODE: software running on production servers to handle live users and data for the intended audience. This is different from production quality code, which describes code that meets expectations in reliability, efficiency, etc., for production.

• CLEAN: readable, simple, and concise. These characteristics are crucial for collaboration and maintainability in software development.

• MODULAR: logically broken up into functions and modules. This makes your code more organized, efficient, and reusable.

• MODULE: a file. Modules allow your code to be reused by encapsulating it into files that can be imported into other files.

Write Efficient Code

Knowing how to write code that runs efficiently is an essential skill in software development. Optimizing your code to be more efficient can mean making it:

• Execute faster

• Take up less space in memory/storage

The project you’re currently working on would determine which of these is more important to optimize. If you are performing lots of different transformations on large amounts of data, this can make a big difference in performance.

Refactor Your Code

Refactoring means restructuring your code to improve its internal structure, without changing its external functionality. This gives you a chance to clean and modularize your program after you’ve got it working. Here are the benefits of refactoring.

• You know it isn’t easy to write your best code while you’re still trying to get it working. Allocating time to refactoring is essential to producing high-quality code. Despite the initial time and effort required, this really pays off by speeding up your development time in the long run.

• You become a much stronger programmer when you’re constantly looking to improve your code. The more you refactor, the easier it will be to structure and write good code the first time.

Add Meaningful Documentation

Adding additional text or illustrated information that comes with your code can be helpful for clarifying complex parts of code, making your code easier to navigate, and quickly explain how and why different components of your program are used.

Several types of documentation can be added at different levels of your program:

• In-line Comments — line level

• Docstrings — module and function level

• Project Documentation — project level

In-Line Comments

In-line comments are text following forward slash symbols // throughout your code. They are used to explain parts of your code, and really help future contributors understand your work.

    const uniqueSort = function(array) {
      // keep trak and remember values we've already seen.
      const breadcrumbs = {};
      // array of unique values
      const result = []

    for (let i = 0; i < array.length; i++) {
        // start loop at 1 as element 0 can never be a duplicate
        if (!breadcrumbs[array[i]]) {
          result.push(array[i]);
          breadcrumbs[array[i]] = true;
        }
        console.log(breadcrumbs)
      }
      return result.sort((a, b) => a - b);
    }

    console.log(uniqueSort([4,2,2,3,2,2,2]))

    // => [2,3,4]

Docstrings

Docstring, or documentation strings, are valuable pieces of documentation that explain the functionality of any function or module in your code. Ideally, each of your functions should always have a docstring.

Docstrings are surrounded by /** and **/ The first line of the docstring is a brief explanation of the function’s purpose.

    /** 
     * function that returns an array with all the elements but the nth.
     * By "the nth term" we are referring to an expression 
     * that allows us to visualize and work with a value at 
     * the "nth" position (an arbitrary position.) 
     * in a sequence of numbers.
     */
    function getAllElementsButNth(array, n) {
      return array.splice(n, 1);
    }

    var output = getAllElementsButNth(['a', 'b', 'c'], 1);
    console.log(output); // --> ['a', 'c']

Project Documentation

Project documentation is essential for getting others to understand why and how your code is relevant to them, whether they are future users of your project or developers who want to contribute to your code. A good first step in project documentation is a README file. Often this is the first interaction most users will have with your project.

At a minimum, this should explain what your project does, list its dependencies, and provide sufficiently detailed instructions on how to use it.

Use Version Control

Learn to use GIT for version control for easy management of file changes. The benefit of using version control in your project is more clear in a professional setting. Multiple developers can work independently to add features to a single project without impacting the work of others, and if there is a bug the code can be reverted back to a stable version.

If you follow these best practices soon it will be clear that this is the correct path and that your efficiency increases because your code is less prone to bugs and redundant code.

Thank you for reading.