Up
Documenting Object Files using HTML Comments - Tamberra
Here at Tamberra, we see ourselves as professional digital problem solvers. We love a good mystery and that is what your project might be at this stage… a mystery. Who, what, where, when, why – these are all questions that we can help you answer.
Tampa, Web Development, Web Developers, Web Applications, Tampa Bay, Programmers, Newspaper Web Developer
15016
post-template-default,single,single-post,postid-15016,single-format-standard,do-etfw,woocommerce-no-js,ajax_fade,page_not_loaded,,vertical_menu_enabled,side_area_uncovered_from_content,columns-4,qode-theme-ver-7.5,wpb-js-composer js-comp-ver-5.1,vc_responsive

Documenting Object Files using HTML Comments

html comments

05 Aug Documenting Object Files using HTML Comments

Posted at 22:24h in Blog by Stacey Jenkins 0 Comments

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.

 

Stacey Jenkins

Stacey Jenkins

Stacey has 15+ years of project implementations under her belt. From very large to very small, she has managed, analyzed, built, and tested systems and then trained teams how to use them. Specifics are on her linkedin, but at the end of the day, Stacey enjoys building things that give real value to the business at hand. She loves this stuff.
Stacey Jenkins

Latest posts by Stacey Jenkins (see all)

Tags:
, , , ,