Focus on why instead of who and when

Please treat this post as a starting point in the discussion about the topic: documentation of the code. At one of the training which I gave, I said:

you do not think anymore about who and when did the change in the code.

But does it mean you do not need to do documentation in the code at all?

Looks familiar?

In the past, I was told to mark my changes in the code using my id and the number of the change. And never remove the code which was changed or not needed – but comment it instead. It means you could end up with something like this.

In a longer period, it was not readable and did not have any benefit after a year or two.

Do we need it anymore?

Nooo. Those who are using Git and for example, Azure DevOps have all that data out of the box.

When you do the commit and add # and number of your work item it will automatically be assigned to it.

So now we can focus that our Git history will look like a real timeline of the project – showing what was changed in the code.

I think we should pay more attention to our commit messages. They should have some meaning. And should be readable to all developers which will work on the project in the future.

Learning from C#

Another point which I would like to begin is that (at least on a project where I worked) it wasn’t always shown why some function (procedure) had been written. And how to use it.

Now we also can focus on documenting why we need the procedure, what are the parameters and what is the return variable.

We can learn from C# but also from… “our” Microsoft Team. In C# in the code documentation is done using XML tags such as <summary>, <param> and much more. The whole documentation can be found here: https://docs.microsoft.com/en-us/dotnet/csharp/codedoc

Also, Microsoft is using it. If you would go to any System App codeunit you will find that all procedures which are exposed have special documentation before it.

Snippets for you

In our team, we decided that in projects we will also use those documentation tags. So, for example, all procedures which are crucial or are in the libraries which we use for automated testing will have similar documentation.

And since it has got always the same structure, I prepared the snippets with the most popular tags. You can find them on GitHub here:

https://github.com/mynavblog/Examples/blob/master/DocumentationSnippets.json 

You just need to copy them to your user snippets. Then you can use them – just write starting from < and you see all snippets for documentation.

Also you can find the snippets in AZ AL Dev Tools/AL Code Outline for Visual Studio Code which works even smarter since they already insert all parameters and return values. More info you can find here: https://github.com/anzwdev/al-code-outline#documentation-comments-support

Below you can see example from the support site.

See documentation in VS Code

I wish that in future we also be able to see the documentation done in this way in VS Code when using intellisense (similar to Java). Now it is not working but some time ago I had seen this as a point in the new features for AL and Business Central but sadly it disappeared.

I hoped that it will be announced as one of the features for the April release – unfortunately, it isn’t. Nevertheless, I think that it is a good idea to document your code in such way.

What do you think?

3 Comments

Leave a Reply to RedFox Cancel reply

Your email address will not be published. Required fields are marked *