The importance of documenting code

I have worked as a software developer for the better part of a decade. There are many different things experience has taught me concerning ways to make my job easier, and better yet, make other developer's lives easier.

One of the things that I don't see others do enough, and I catch myself slacking on at times, is providing documentation for code.

I am not referring to building a Word Document with every level of detail about the code and how it works. I am referring to simple things like putting comments in your code and building README.md files in your code repositories.

I try to do both of these things consistently, because not only does it help others who may come after me that need to know what the code is and maybe why I did something a certain way, but also because it will likely help me out in the future as well. I work for a company that provides custom software solutions. Some projects are small, some are larger. One thing that is consistent though is that I touch on average about 4-6 projects a week. With all the context switching of switching between projects and usually clients as well, it is hard to keep track of all the code and why I did something a certain way.

There are two great ways of documenting your code. You can leave comments in your code and you can leave a README.md file in your code repository.

Commenting Code

Leaving a quick note in the code helps me not only remember what I was doing, but also helps me find snippets of code easier when I am troubleshooting. Pretty much every programming language has some way for you to comment a line in your code. The most common ways are shown below.

# Languages: PHP, Python
# This is a comment

// Languages: C++, C#, JAVA, PHP
// This is a comment

-- Languages: SQL
-- This is a comment

/*  
Languages: C++, C#, CSS, JAVA, PHP
This is a multiline comment
*/

In C#, you can even place comments on your methods and properties so that the comments will show up in intellisense. This can be done by utilizing a triple front slash.

/// <summary>
/// Description of Method
/// </summary>
/// <param name="value">Description of parameter</param>
/// <returns></returns>
public async Task GenerateAsync(byte[] file)
{
    ...
}

README File

In the current day and age, most code for organizations and even individuals are kept in code repositories. These repositories store the source code as well as change history and usually some form of branching of code to allow multiple people to work on a project at the same time and to have different versions of the code. The most common version control systems of source control out there are git and TFS. There are others such as SVN and Vault that are becoming less common.

In my personal experience, I am seeing git become pretty much the standard version control system. You can find implementations of it in BitBucket, GitHub, Azure DevOps, and many others. It seems to have gained a lot more popularity in the last 5 years or so, even though it has been around since 2005. It was originally developed by Linus Torvalds to allow him to collaborate with other developers on a project he started that you may have heard of called Linux.

Another popular source control system is TFS which is a system developed by Microsoft and released in 2005. This can be found in Team Foundation Services and Azure DevOps. TFS holds a following with developers who are heavily integrated in the Microsoft ecosphere.

One thing most of these different source control systems support is markdown files. These files are text based files that use the markdown syntax and are stored with the file extension .md. The syntax is extremely easy to work with. This blog post is even written in Markdown and is translated to HTML using a library in C#.

The most common markdown file used in code repositories is a README.md, also known as the README file. README files are usually displayed on the webpage in the source control repositories while you are browsing the code. By utilizing these files, you can leave information about what the files in a particular folder are used for. Normally, there is a README file in the root directory of the code base that gives some information about what the application does, how you can set it up, and any other important information you should know about that application.

This is a great way of leaving instructions for collaborators or future developers who will have to look at your code.

To Comment Or Not To Comment

Something that people tend to struggle with is what should be commented on and what should be included in the comments. Frankly, the answer is subjective. Here are some simple rules that I use when leaving a comment in code.

Things You Should Leave Comments About:

1. Basic flow of your code.
2. Changes in requirements that caused you to update code.
3. Formulas or complex logic you used in your code so others don't have to decipher your code.
4. TODOs - Potential enhancements to the code.

Things you should not leave comments

1. Old code - Delete it. That is what code repositories are for. If you aren't using a code repository, why aren't you?

Other things you can do to make your code more readable

1. Use descriptive variable and method names.
2. Create tests for your code so people can see what outcome you are expecting from your code.

Conclusion

Commenting code may be daunting, but it is a beneficial practice that more people should participate in. It may seem pointless at first, but when you have to go back and look at an old snippet of code, it can save you a lot of time trying to find the exact line of code you are looking to update logic on. It is also beneficial for anyone who may have to look at your code in the future. This holds true in organizations where teams of people have to look at code and also open source projects where potentially thousands of developers are collaborating on a single project.

Be kind to yourself and others and leave a comment.

I don't have a comments section yet, so feel free to send me feedback on this blog.