The Power of Documentation

In this blog I would like to share some bad experiences from my work for not having documentation, and how I overcame it.

As a self learned developer, I am always intrigued to jump into computers and start coding. It's almost a bad habit, as it is unproductive, which I've found the hard way.

I work full time for a web-dev company, and thus there is a huge list of clients that I keep working with, often switching from one project to another.

As a new developer, I found myself quickly jumping to code, just for the sake of learning. For example, if a new problem came to me, I would do my research, find the best code, bulletproof it and deliver. However, I always kept documentation at bay, thinking that maybe that's for large scale programmers like react or php, or something, that lots of people use. Soon I found out that I was wrong.

As it is important to solve a problem with research and critical thinking, it also starts to become a problem in itself, when we have to keep googling or researching similar things. With a proper documentation, this has helped me reduce such unproductiveness.

Using DOCBLOCKS to mark my code

One of the most productive form of documentation that I currently do is docblocks on top of functions, comments in code so I can easily search for them, and most importantly, the changelogs.

/**
* This function does something and returns boolean
* @params $anything String
* @author deepyes02
* @return boolean
*
function do_something($anything){
// code
return true;
}

a docbloc example for documenting functions in code

This way, I can search for the keyword 'deepyes02' which can be anything in fact. This will help me locate the functions that I've written in a code that someone else authored. For instance, a website built by someone else that requires my contribution. Clearly things are easy to track, and I save a lot of time instead of scrolling.

Changelogs to track what changed in code release

Even though there's git for more detailed look, I've started using changelog files in each project where I work. If it's not there, I simply create a changelog file (without extension), and push it to the repo.

##################################################
8-15-2022 - made all countries flag visible by default
1.  added flag for Japan:
\xyz\assets\images\flags
2.  edited logic to render all country flag and not just some. wp-\xyz\functions.php -> function get_network_sites() : line 258
3.  Sitemap issue fix in server. 
#######################################################

Changelogs for tracking updates in code.

In the changelog, I mention the date of the code push, and mention of any code changes. This helps me figure out what changed, and have a better idea of the project.

Now, honestly these additional effort required to code definitely sounds more when one is struggling to learn the foundation of programming, which are more important.

However, as you've started to gain skills, and find yourself on a crossroad, where you can choose to be more productive, it definitely helps.

Afterall, what's a programmer without a toolbox?