Friday, 14 September 2012

How to comment when modifying standard code [AX 2012]

I have seen many ways of modifying standard code and how commenting is done. The best practice is to make as little change as possible or as little impact to the standard solution as possible. Otherwise, making it stand out and the next person can clearly see the difference between standard code and custom code.

Looking at how the Feature pack incorporates the Extension model is very interesting.

See the screenshot below. You can see how the standard code is commented out with the <SYS> tag. Then the changes are added with their tag <PSA> or <RETAIL> as illustrated in the screenshot below.

clip_image002

Now if you look at the compare, it stands out. If for some reason you had to revert your custom code back to the original. You just delete your code between your tags and uncomment the <SYS> tags.

Compare2012-06-12_1002

On msdn there is a best practice on how to do code commenting.

http://msdn.microsoft.com/en-us/library/cc967435.aspx

It clearly says:

Do not use multi-line syntax /* … */ for comments. The single-line syntax // … is preferred even when a comment spans multiple lines.

Obviously, Microsoft developers have found that using /*…*/ in this case resulted in better readable code.

I would be interested to hear other developers thoughts on this topic.

No comments: