Importance of documenting code. Is it worth the effort?

Importance of documenting code. Is it worth the effort?

Andrew Velez
Posted on 12/16/2018

Documenting your code is so fing important. If you expect the project you are working on to make money or you will be spending a lot of time on the project than it is extremely important to document your code. It will make your life easier in the long run. I'm gonna write out some of my favorite reasons to document code.


Reason #1: Allows you to remember what you were doing

Have you ever gone back to some code you worked on in the past and thought to yourself what the hell was i writing? Well that what documentation is for. It is really hard to remember everything you were doing in the past that why it is important to not only separate your code into nice components but to also document it. When you document your code, it is a quick way to get in the mindset of what you were doing since what you coded will be in plain English.


Reason #2: It makes it a lot easier to work with other people when your code is documented.

This is a really important reason. Even if you are someone who thinks their project wont have a lot of people on it. Usually if it's a project worth creating eventually you are going to want to maintain it. Paying someone to maintain your code is a great way to save yourself a ton of time and allow you to work on other projects that are more lucrative. There comes a point where if you are making so much from the app its better to just higher some kind of support engineer for cheap on freelancer.com.

Another point i would like to make is that you could also get to the point where what you are coding could be its own stand alone tool aside from your game. If you are documenting religiously it makes it a lot easier to distribute packages and reuse in other projects. For example you might find yourself making a spawnmanager that allows you to place waypoints. If in another game you want to change from 2d to 3d it would make it a lot easier to go into the code if it was documented.


Reason #3: You're less likely to make errors.

When you are coding sometimes you start to just get into a rhythm of coding. Sometimes this is when you write your best but other times you put yourself in a whole with the amount of time it would take to maintain your code. By thinking more logically about your code and having to write it out in plain text you are forced to evaluate your code. A lot of times you'll find you wrote code inside a method that doesn't make to much sense.

After you finished the functionality of some feature you can take the time to separate out methods into more easily maintainable chunks. You have to remember that Clear Documentation is not only explicit but implicit. That means your variable names and method names should also be descriptive. That is why it is import to separate into maintainable chunks because the longer a method gets the less relevant its name is.


Reason #4: Having more code to go back to and reuse allows you to become a better programmer.

When coding you will find that a lot of times when you are doing something you'll find that you already did a variation of that task in the past. If you are always documenting using that old code is easier. That code is also way more likely to work with your newer system since all the little intricacies are explained.

Example: I wrote a Comment Component in React for this website. That Component is a little strange because it requires you to pass in the object that owns the comments in the database. This allowed me to easily add a comment section to any part of my database. I wanted to have the comment section embedded to its parent. For example the entry for this Article would have its own Comment Section entry. This is the NoSql Approach i took using Firebase.

Because i took the time to document the Comment section i was able to easily use it in other pages like my Games. All had to do was read what the class needed and I was up to date to what i had done a year ago.

Article: { comments: [ { ... }, { ... } ] }


When You're first starting off it might seem like documentation is a waste of time but the truth is that it's one of the most important things you can do. If you plan on being a programmer for a long time i would get in the habit of adding comments to your code.


C# Example


/// < summary >
/// Method that returns a refrence to the varaible image.
/// < returns >the image the user added to webpage.< /returns >
/// < /summary >
Image GetImage()
{
return this.image;
}



Javascript Example

/**
* @description Method that returns a refrence to the varaible image.
* @return Image the image the user added to webpage.
*/
Image GetImage()
{
return this.image;
}

Andrew Velez
Posted on 12/16/2018

...

Recomendations

Games for Sale

Comments 0

Display Name

Email


0 / 10