SEARCH:

NAVIGATION:

JSArchive

Good software development practice dictates that code should be sufficiently self-documenting that other knowledgeable developers would be able to follow the algorithms no matter how abstruse. Java developers have an advantage when creating documentation: a tool that will scan your documentation and point out each and every bit that you missed in the API. However, regardless how you arrive at a well-documented module, once you do, your file could easily be two to three times its original size. For compiled languages, such as Java, this is not an issue at all, since the compiler does not concern itself with non-code portions of a file. JavaScript, on the other hand, is an interpreted language, which simply means that every line must be scanned at run-time and handled appropriately; including any documentation lines (i.e. comments), which are then ignored. Further impact is that JavaScript is used essentially exclusively as a scripting language inside web pages, which are fetched over the network using whatever bottleneck your internet connection is filtered through. For high-speed networks, this is not terribly significant, but for dial-up, it could certainly be.

Astute readers of CleanCode commentary will observe (in the Web Guidelines section) a guideline that dictates smaller is better when it comes to not only graphics but also code files (html, javascript, etc.) Which, of course, is in direct conflict with well-documented code, as just explained. That's where JSArchive comes in to play, offering both compression and consolidation. This utility can strip out not just comments, but most unnecessary whitespace in a file to create a production version, if you will, that is streamlined for transmission. Furthermore, it will take a collection of files and bundle--or consolidate--them into a single archive while compressing. This is advantageous because network throughput can be increased not just by smaller files, but also by a smaller number of transactions. Each graphic, script file, css file, etc., requires a transaction between your browser and the remote server. Less files therefore means less transactions.

So let's take a peek at JSArchive. First, when you execute JSArchive, you will actually get two files, an archive containing the compressed/consolidated files, and a log file, containing information about the execution. Here's an example log file from creating the JavaScript archive used on the CleanCode web site. You'll observe that the amount of compression may vary dramatically from file to file. Also, the final figures tell you the overall compression factor.

Creating archive: /usr/ms/devel/cleancode/js/MenuArchive.js
file: ../netscape/ua.js (compressed 59% / saved 41%)
---------
file: ../cooldev/coolmenu.js (compressed 89% / saved 11%)
  class: get
  methods: check, div
---------
file: ccmenu_local.js (compressed 56% / saved 44%)
---------
file: ../cleancode/util/NavKeys.js (compressed 19% / saved 81%)
  class: NavKeys
  methods: init, assignKeys
---------
Archive '/usr/ms/devel/cleancode/js/MenuArchive.js' complete (compressed 64% / saved 36%).
4 file(s) processed.

Default program operation creates a log file, as shown above, but you will see nothing on the command-line, except in the case of errors. JSArchive is designed that way so it may be used either as a command-line utility or called programmatically as a library component. From the command-line, however, it is often useful to have feedback from the program while it runs as well. Simply use the verbose command-line flag (-v) and you'll then get output as shown below, similar to the log file shown above:

C:\usr\ms\devel\js\ccwebpages>java com.cleancode.format.JSArchive -v -c -o "/usr
/ms/devel/cleancode/js/MenuArchive.js" ../netscape/ua.js ../cooldev/coolmenu.js
ccmenu_local.js ../cleancode/util/NavKeys.js
Creating archive: /usr/ms/devel/cleancode/js/MenuArchive.js
../netscape/ua.js... 59%
../cooldev/coolmenu.js...  89%
ccmenu_local.js... 56%
../cleancode/util/NavKeys.js... 19%
Archive '/usr/ms/devel/cleancode/js/MenuArchive.js' complete (compressed 64% / s
aved 36%).
4 file(s) processed.

In this illustration, MenuArchive.js is the target archive to be created. Four files will be consolidated into this single archive file. Because of the compression flag (-c), the files will be compressed while being consolidated, stripping out most unnecessary whitespace.

Inside the archive, JSArchive adds an initial comment block specifying the name of the archive, the creation date, the version of the generator, and the command that created it. Here's an example:

//////////////////////////////////////////////////////////////////////////////
// Archive: MenuArchive.js
// Created: Fri Apr 02 12:50:41 MST 2004
// Generator: JSArchive [1.12]
// 
// The command line arguments to generate this file:
// com.cleancode.format.JSArchive -v -c -o MenuArchive.js
//    nc:../../cleancode-support/license/mpl-c.txt ../netscape/ua.js
//    ../cooldev/coolmenu.js ../cleancode/Util/Version.js ccmenu_local.js
//    ../cleancode/Util/NavKeys.js
// 
// This file was generated automatically and should not be edited manually.
//////////////////////////////////////////////////////////////////////////////

Then, in front of each file, JSArchive also records the file name, how much it was compressed, and its last modification date, e.g.:

// ../cleancode/util/NavKeys.js (compressed 23% / saved 77%)
// last modified: Sat Nov 22 20:40:48 GMT-07:00 2003

One handy--and unique--feature of JSArchive is that you may selectively choose to leave specific files uncompressed while compressing all the rest. A common use for this is to add a comment block at the top of a file that contains license and copyright information. In the above example, you'll see the license file added, including the nc: prefix, specifying no compression.

Caveat: JSArchive is somewhat unpolished; it was made robust enough to handle the several uses needed for CleanCode itself, but it is not bulletproof. It is possible that the compression algorithm still has some flaws in it, so it is prudent to test your code with and without compression. You may want to compare JSArchive to Mike Hall's fine JavaScript Crunchinator.

Copyright © 2001-2013 Michael Sorens • Contact us • Privacy Policy
Usage governed by Mozilla Public License 1.1 and CleanCode Courtesy License