CodeNotes.txt #1

=== Notices

Originally developed for Perforce by VIZIM (www.vizim.com)

Copyright (c) 2014 Perforce Software, Inc. and VIZIM Worldwide, Inc.
All rights reserved.

Please see LICENSE.txt in top-level folder of this distribution for
license information

=== Introduction

This file is background information for those looking to understand, update
or modify these tools. The file Migration.docx in this distribution is
oriented toward end users.

Before making modifications, consider that the majority of users for these
tools have one or more of these characteristics:

(1) They are not familiar with packages that don't have installers.
(2) They are not familiar with perl.
(3) They are not familiar with CPAN.

You should also assume that they follow the installation instructions and
procedures specified in the migration document.


=== Coding style

Each of the tools is a standalone monolith. Most of the tools are small,
there is limited commonality to the functionalities, and modules add setup
complexity.

The general programming style is procedural. There is commonality to format
and naming but no specific published standard was used. Complex data
structures are commented. Most of the remaining comments either (a) provide
processing markers, or (b) document a correction to a logic error that
caused a test to fail during development and support.

The code could be more compact. However, the priority consideration was
coders who may not be that familiar with perl. Of course many perl coders
don't usually deal with hashes of hashes, hashes of arrays, arrays of
anonymous hashes and references. But there is no practical way to avoid
using these constructs.


=== CPAN modules

Modules that are not part of the standard ActivePerl distribution have
been avoided. This includes modules that may be readily available
through CPAN.

The primary reason for this is to reduce the install overhead. There
are also organizations where CPAN installation is problematic for
various policy reasons.


=== Perforce Perl API

The Perforce Perl API was not used. Unlike more general purpose applications
the import code requires well defined command responses. Using the API
does not simplify much of the code and has a minimal impact on performance.
Moreover, there are environments where available Perl distributions do not
align with the available versions of the API. Overcoming the availability
issue by making a local compile of the API an install requirement is
undesirable given the minimal value to the import code.


=== TFS APIs

There are version dependencies that exist with the TFS APIs. The required
extraction information is easily established using command line commands
that don't have version dependencies.


=== XML

Although many of the files generate what appears to be XML the files are
not intended to be valid XML. However, the XML syntax is useful so it has
been adopted.

It wouldn't be difficult to make these files valid XML. In fact they were
originally valid XML. The problem encountered was that processing of
large (often several 100 Meg) files using the standard distribution XML
modules was significantly slower than the code that currently exists. Given
the long run times for some of these tools, increasing the run time for
format purity was undesirable.