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?
It is good to have Git and it is OK when you develop a solution and support it, but we have huge the problem – when you fix the issue from remote Customers or develop new functionality based on existing code. The issue – you never know what did these changes and why? Even the Customer does not know what it is were.
Like final comment – the Git is good for the development center, but not end customers
Do not agree with RedFox, git is good even for end-customers. Question is, are end-customers good to develop for BC? And I think there is a big problem…
Kine, I just shared my personal knowledge from several real big projects (where End-customers “changes” or “rotate” team several times and finally, no-one understands whats is going inside code) and don’t want to argue about it (because I’m happy that you avoided this point)