diff options
Diffstat (limited to 'Master/tlpkg/doc/coding-style.txt')
| -rw-r--r-- | Master/tlpkg/doc/coding-style.txt | 33 |
1 files changed, 33 insertions, 0 deletions
diff --git a/Master/tlpkg/doc/coding-style.txt b/Master/tlpkg/doc/coding-style.txt index a6aac4a7211..0cf1a022b87 100644 --- a/Master/tlpkg/doc/coding-style.txt +++ b/Master/tlpkg/doc/coding-style.txt @@ -78,3 +78,36 @@ standards' recommendation of putting braces on lines by themselves, thus eating up precious vertical space. Do not do that. +* Exporting symbols and keeping namespaces clean. + +In general, the only things which should be in @EXPORT are those +which are needed nearly universally, such as debug and log. Barewords +like somefunc are preferable to prefixed &somefunc. + +In contrast, EXPORT_OK should list all the "public" symbols (but not +private ones) of a module. It is good to list them in the same order as +they are defined in the file, since that both makes it obvious where a +new symbol should be added, and provides a sort of check that all and +onyl the right symbols are there. The EXPORT symbols need not and +should not be listed again in EXPORT_OK. + +Then, use TeXLive::SomeModule; +will import all the EXPORT (but not EXPORT_OK) symbols. + +If you need to import a few EXPORT_OK's in addition to the EXPORT's +use TeXLive::SomeModule (:DEFAULT oksym1 oksym2); +instead of redundantly listing the @EXPORT symbols. + +If you only use a symbol once or twice, don't import it at all. Just +use TeXLive::SomeModule::somesym. This has the advantage that someone +reading the source will know immediately where it comes from, and that +it's not local. This is especially useful with $variables, which our +brains tend to think of as "local". + +If you want to import every single EXPORT_OK symbol, +use TeXLive::SomeModule (/./); +should do it (I've never actually tried it). This is certainly far +better than explicitly listing every symbol yet again. + +Documentation: +http://search.cpan.org/~ferreira/Exporter-5.63/lib/Exporter.pm |