Documenting your code, is it important?

As a programmer, I have faced situations in which I have to reuse my code from a previous project, since maybe, on another eLearning project, I have need functionality that I have already programmed. I have also faced situations in which I have had the need to use code from another programmer.

Unfortunately, and it has happened with my own code as well, not all the time the code that I need to reuse, is well documented. By “documented”, I mean adding annotations that explain what’s happening in each part of the code. This can be easily done when you use different programming languages, like HTML, JavaScript or PHP, to not mention more.

But what happens when you create eLearning modules using a rapid eLearning authoring tool like Articulate Storyline or Adobe Captivate? Since software like these ones, don’t have a space in which to add comments, we need to create a different way to document our code for future projects.

So, to answer the question on the title of this blog, it is not only important, but also a good practice to document your code, for example, if you can’t comment your functionality right next to the code, you can always create Word documents explaining the different parts of the code, and even include screenshots to make things even clearer.

As an example, let’s assume we have an eLearning module with a click and reveal interaction. We have two buttons, that when you hover over them, their state will change, and when you click on any of them, a layer with some information, will be revealed.

How do we document this?

Let’s begin by showing the context of the eLearning module with a screenshot:

It is important to show as many elements of the interaction as possible, to understand the flow of our programming. On the screenshot above, we can see the interactive elements, the states that we have programmed, the triggers and the layers that will be revealed when clicking on any of the buttons.

Then, describe each section that contributes to the interaction. Try to use a simplified language to avoid any kind of misunderstandings and specify the section you are talking about, preferably using the heading styles in Word. If necessary, you can add screenshots focusing on each of the sections. For example, if you are discussing the states, you can use a screenshot like this:

Or you can even have the same screenshot with a highlight, like this:

The most important part is to be as clear as possible, and if you are introducing a functionality for the first time, it’s important to give a brief explanation, so that a future programmer understands how that functionality impacts our eLearning module, but the reader still keeps the focus on the interaction we are building. You can even link to another website that explains that interaction more in depth, if it’s not relevant to explain on our process document.

Remember to create this type of document as often as possible, to avoid some serious headaches in the future.