In the previous post I laid out the scaffolding for my back end code. It took a little time to think through the code I would need. I referred to some past projects and a tutorial I had taken when I was first learning React. During the process of pseudo-coding there were a couple times where I felt like the effort was outweighing the eventual benefits. What’s the point of writing one comment line to describe another single line importing a model after all?
After completing the process, I felt different about that “extra work”. The result was akin to painting by numbers. Once I finished pseudo-coding, it only took a fraction of the time I would normally spend writing up a node API to get all of the pieces in place and functioning properly. I was able to cut and paste some code from older projects quickly and easily given that every piece of functionality already had a home in the document. The structure of the pseudo-code comments also made writing the completely new code blocks a breeze. The concept of what needed to happen was already in place, so I saved a ton of time in trying to think through the logic on the fly. Additionally, my code is much easier to follow because I left many of my pseudo-code comments in place or modified them slightly to explain what each piece of logic was doing.
In a real-world production environment, this may be overkill. I’m aware of the debate that surrounds comments and the addage “Write fewer comments by writing cleaner code”. The idea behind this phrase is that if your code is written well enough, comments become unnecessary because your code can speak for itself. I’m not sure I’ll ever fully adopt this mindset, as I find it much easier to not only understand what I’ve written but also to navigate the document seeing the comments acting as headers for each block. At least for my personal projects, I intend to continue writing comments that explain what is happening in each significant section and just let the compiler make up for my inflated file sizes. Here’s an example of my commenting practices in the server.js file:
Similarly, in my routes files, having this “roadmap” in place allowed me to think about some future development ideas and leave breadcrumbs for adding new features in the future. For example, since this app is designed to track progress in weight loss and blood pressure, it’s not practical for a user to easily be able to go back and edit or delete old entries. Ideally you would want your user to have that ability but place it behind a roadblock that requires the user to confirm they want to edit their history and be aware of those implications. Since that was outside the scope of my initial minimum viable product definition, I left room for it in the API and color-coded the future development notes using Better Comments VSCode extension.
Notice the route definitions on lines 16-18. This is a labeling convention I picked up by following the React Front to Back Tutorial by Brad Traversy. I mentioned his tutorial in the previous post and loved this idea of having detailed descriptions of each route so I’ve implemented it in my own API’s. Thanks Brad!
I’d love to tell you that server.js fired right up on the first try after finishing the coding process. I’d love to, but I can’t. A few oversights still popped up and I had to troubleshoot a couple of minor bugs in my routes before I got to this beautiful console message:
Now it was time to test out my API using one of my favorite tools in all of web development; Postman. Postman is a free (for solo developers) tool for testing REST API’s during development without having a front end client. You can download it here. I’ll write a post dedicated to using Postman in the future, but for this post, I’ll share some screenshots and give an overview of how it is used.
Postman allows you to create HTTP requests using a URL field similar to what you would find in a web browser like Chrome, Firefox, or Safari:
Sometimes these requests can get pretty complex and so as you develop your API you can save collections of requests and easily access them later as you update or modify your API.
Postman returns the body of your request in easy to read JSON format as well:
Side-note, Batman is a gracious alpha-tester for most of my API work.
Just like in the console previously, not all of my requests worked perfectly the first time. On the whole, however, this pseudo-coding process turned what used to be a day-or-three-long project into a functioning node server and REST API in just a couple hours. Next up, we bootstrap the front end client and pseudo-code the front end UI in React!