As you might know, XMLDOCS documentation system contains
bin/stattree
script which parses complete Interchange
source tree. Even though it really tries to recognize code regardless
of formatting (much like Perl interpreter does), there are still some
little suggestions on the programming style to make it easier for XMLDOCS.
Do not use the hash character #
in weird contexts.
Use it only for comments (putting a space between eventual code and inline
comment) or simple substitution such as s#A#B#g
.
(Impact: cosmetic)
# Line comment my $test = 12; # Only used for test
Do not break word sub
and subroutine name to separate
lines.
sub test....
is OK, sub \n test
is NOT.
It's best to use the cleanest variant that matches regular expression
^sub \w+ {$
.
(Impact: might confuse function tracking code)
sub test1 {
Do not break obviously "solid" blocks of code to multiple lines. To give
you an idea of what I am talking about, let's say you should not break
typical xmldocs regexps, such as /\$::Pragma->{(\w+?)}/
or /\$Vend::Cfg->{Pragma}{(\w+?)}/
. (Impact: important. Might prevent the bin/stattree
script from detecting symbols)
return if $::Pragma->{download}; if ( $Vend::Cfg->{Pragma}{download} ) {
Do not break blocks of code that obviously follow a lexical pattern. For example, do not introduce double quotes or structural changes to the below:
['FormAction', 'action', ''],
['MaxServers', 'integer', 10],
['GlobalSub', 'subroutine', ''],
['Database', 'database', ''],
['FullUrl', 'yesno', 'No'],
['Locale', 'locale', ''],
['HitCount', 'yesno', 'No'],
['IpHead', 'yesno', 'No'],
['IpQuad', 'integer', '1'],
['TagDir', 'root_dir_array', 'code'],