The Importance of Proper Code Structure and Documentation

Imagine this. You’re looking for a book in a library. How do you navigate yourself to the book? You look at the different sections of the library and then the corresponding subsections until ultimately you find the book that you were looking for. Now imagine, all the books in the library are kept randomly. There is no order, no structure to where which book is kept. It would be a nightmare to search for your book in this case, wouldn’t it? Well, developers often face this exact issue while working on different projects. There are a number of different practices that one should follow while collaborating with other programmers.

Folder Structure

When we start programming, we often gloss over this very important concept, the structure of the code and project. Let me ask you a question by showing you two ways of doing the same project. Which of these two folder structures do you think is the better way to go?

Two different ways of structuring the same NodeJS project

The project on the left has folders defined for different aspects of this NodeJS project, including routes, schemas, and a lot more. Some might say that the picture on the right is the correct way to go. However, all experienced developers will always opt for the structure on the left. When we work on different projects, it can get annoying to navigate between different files if we choose to store our files without a proper folder structure. It gets confusing not just for yourself, but for other developers trying to see your code as well. Without labelling your folders, it is incredibly frustrating for not just external developers, but also for other programmers working with you on the same project, to navigate through the code. File organization is key for collaborative projects and a good folder structure reduces clutter and is an important and necessary feature for any project.

Code Structure

Just like organising folders, code structure is key for a good project. A good one keeps things smooth and easy, not just for other collaborators, but for yourself too. Quality readable code helps in future enhancement scenarios when production changes have to be maintained. If you’re looking back at your code after a long while, it can often be confusing to understand the flow of every snippet of your code.

Two ways of writing the same code

Out of these two snippets of the same code, which seems more readable? It would be pretty apparent that the one on the right is the better-written one, but why is that? Is it because of the indentation? Is it because of the brackets? Or is it just some brain psychology? Well, it’s a mixture of everything. The code on the right is easier on the eyes and is well divided into segments with proper indentation. It’s always good practice to have well-structured code as it helps with better code readability and makes it easier to navigate through your program. The VS Code extension Prettier can be used to beautify your code automatically.

Code Documentation

Lastly, we’ll talk about code documentation. What is code documentation? Code documentation is the practice of describing and explaining how a piece of software works. It includes various types of documentation, such as:

1. Comments: In-line comments in the code that explain specific lines or sections, making it easier for other developers (or even yourself in the future) to understand the purpose or functionality.

Comments are supposed to be useful information

2. Documentation Files: These include separate files or documents that describe the overall structure of the codebase, its purpose, how to use it, and any guidelines for contributors.

Postman Documentation

This image shows an example of documentation made with Postman. It provides collaborators with a clear representation of the expected output.

3. API Documentation: For libraries or frameworks, this documentation explains how to interact with the code — its functions, classes, methods, and their expected input and output.

API Documentation allows other people to understand how to use your product

In a nutshell, having well-organized code and clear documentation is like giving your programming project a solid backbone. It’s not just about making things easier for other developers; it’s about making your own life simpler too.

Imagine a messy room with stuff scattered everywhere — it’s a hassle to find what you need. The same goes for code. When you neatly arrange your code into folders and files, it’s like having labelled drawers for different things you own. It just makes everything easier to find and work on.

Also, writing code in a way that’s easy to read, like using proper spacing and indentation, is a game-changer. It’s like writing a story with good paragraphs and punctuation; it just flows better.

Don’t forget about comments and documentation. They’re like giving your code a roadmap. It helps anyone, including your future self, understand what each part does and how to use it.

So, just like a librarian organises a library for people to find books easily, you should organise your code. This not only helps others understand your code but also makes it easier for you to go back to it and make improvements. It’s all about keeping things straightforward and hassle-free.