In any development team of a size greater than 1, it is best practice to document your code. At Tamberra, we have worked with many development teams on Saxotech templating, ranging in time from weeks to years. It is often times consuming to first understand which assortment of templates and object files comprise a page. It can also be hard to decipher the purpose of an object or macro file upon finding it.

 

As consultants, our goal is to help teams quickly develop a piece of functionality, and also leave it in a state that is easy for future developers to maintain. We achieve this in our macros and object files by putting a comment block at the top of every file.

 

Each comment block contains the file name and path to that file. It also contains the author, date and description of the file:

 

We also like to keep an area for tracking file modifications:

Once a file has been in use for a long time, we can see the history of changes to the file.

 

You’ll notice that the HTML Comments are wrapped in SAXOTECH object script. This keeps the HTML from automatically outputting into the source code for all the world to see. We want to keep our comments inside the code and isolated to the developers. The object script says “if the varialbe HTMLComments exists or has value, then output the code in this block”. Since HTMLComments doesn’t exist, the HTML comments will not be output. However, there is a trick. You can add this query parameter to your templates URL string and see the comments in the source code.

 

For example, take this current page, and add ‘&HTMLComments=1’ to the URL. The macro file can access the query parameter and then the object script evaluates to true and you can see it in the page source. Try it now! Add the query parameter and then view source for the page. Note that this won’t work for the object files as they don’t have access to the query parameters by default, but we like to use this format regardless to keep consistency in our code.

 

This best practice can be very useful for speedy and efficient development on your teams.