Error processing request

Parameters

Body

Error

Unknow state transition: LINE -> END

-code

1

-level

0

-errorstack

INNER {returnImm {Unknow state transition: LINE -> END} {}} CALL {my render_wikit {Tcl Style Guide} Coding\ style\ is\ often\ the\ subject\ of\ heated\ debates,\ of\ almost\nreligious\ fervor.\ \ But\ the\ bottom\ line\ is\ that\ consistent\ \ncoding,\ following\ a\ reasonably\ well\ thought\ out\ style,\nwill\ produce\ more\ readable,\ maintainable,\ and\ bug-free\ncode\ than\ arbitrary\ free-form\ off-the-cuff\ programming.\n\nTcl\ is\ no\ different\ in\ this\ respect.\ \ All\ Tcl\ application\ and\nlibrary\ code\ can\ benefit\ from\ following\ simple\ guidelines\ that\nwill\ make\ the\ code\ more\ readable\ and\ reliable.\ \ Some\ nice\ndocumentation\ is\ already\ available\ in\ the\ form\ of\ the\n''Tcl\ Style\ Guide''\ by\ Ray\ Johnson,\ which\ is\ available\ at\nhttp://www.tcl.tk/doc/styleGuide.pdf\ .\ \ This\ \ndocument\ describes\ high\ level\ conventions\ for\ writing\ scripts\nsuch\ as\ naming\ conventions\ and\ file\ organization.\ The\ following\ document\ outline\ is\ a\ wikified\ version\ of\ that\ PDF.\n\n----\n\n'''Document\ Outline'''\n\ \ \ 1\ Introduction\n\ \ \ 2\ Executable\ files\n\ \ \ 3\ Packages\ and\ namespaces\n\ \ \ 3.1\ Package\ names\n\ \ \ 3.2\ Version\ numbers\n\ \ \ 3.3\ Package\ Namespaces\n\ \ \ 3.4\ Structure\n\ \ \ 4\ How\ to\ organize\ a\ code\ file\n\ \ \ 4.1\ The\ file\ header\n\ \ \ 4.2\ Multi-file\ packages\n\ \ \ 4.3\ Procedure\ headers\n\ \ \ 4.4\ Procedure\ declarations\n\ \ \ 4.5\ Parameter\ order\n\ \ \ 4.6\ Procedure\ bodies\n\ \ \ 5\ Naming\ conventions\n\ \ \ 5.1\ General\ considerations\n\ \ \ 5.2\ Basic\ syntax\ rules\n\ \ \ 6\ Low-level\ coding\ conventions\n\ \ \ 6.1\ Indents\ are\ 4\ spaces\n\ \ \ 6.2\ Code\ comments\ occupy\ full\ lines\n\ \ \ 6.3\ Continuation\ lines\ are\ indented\ 8\ spaces\n\ \ \ 6.4\ Only\ one\ command\ per\ line\n\ \ \ 6.5\ Curly\ braces:\ \{\ goes\ at\ the\ end\ of\ a\ line\n\ \ \ 6.6\ Parenthesize\ expressions\n\ \ \ 6.7\ Always\ use\ the\ return\ statement\n\ \ \ 6.8\ Switch\ statements\n\ \ \ 6.9\ If\ statements\ \n\ \ \ 7\ Documenting\ code\n\ \ \ 7.1\ Document\ things\ with\ wide\ impact\n\ \ \ 7.2\ Don't\ just\ repeat\ what's\ in\ the\ code\n\ \ \ 7.3\ Document\ each\ thing\ in\ exactly\ one\ place\ \n\ \ \ 7.4\ Write\ clean\ code\ \n\ \ \ 7.5\ Document\ as\ you\ go\ \n\ \ \ 7.6\ Document\ tricky\ situations\ \n\ \ \ 8\ Testing\ \n\ \ \ 8.1\ Basics\ \n\ \ \ 8.2\ Organizing\ tests\ \n\ \ \ 8.3\ Coverage\ \n\ \ \ 8.4\ Fixing\ bugs\ \n\ \ \ 8.5\ Tricky\ features\ \n\ \ \ 8.6\ Test\ independence\ \n\ \ \ 9\ Miscellaneous\ \n\ \ \ 9.1\ Porting\ Issues\ \n\ \ \ 9.2\ Changes\ files\n\n'''SECTION\ 1'''\n\n''Introduction''\n\nThis\ is\ a\ manual\ for\ people\ who\ are\ developing\ Tcl\ code\ for\ Wish\ or\ any\ other\ Tcl\ application.\ It\ describes\ a\ set\ of\ conventions\ for\ writing\ code\ and\ the\ associated\ test\ scripts.\ There\ are\ three\ reasons\ for\ the\ conventions.\ First,\ the\ conventions\ ensure\ that\ certain\ important\ things\ get\ done\;\ for\ example,\ every\ procedure\ must\ have\ documentation\ that\ describes\ each\ of\ its\ arguments\ and\ its\ result,\ and\ there\ must\ exist\ test\ scripts\ that\ exercise\ every\ line\ of\ code.\ Second,\ the\ conventions\ guarantee\ that\ all\ of\ the\ Tcl\ and\ Tk\ code\ has\ a\ uniform\ style.\ This\ makes\ it\ easier\ for\ us\ to\ use,\ read,\ and\ maintain\ each\ other's\ code.\ Third,\ the\ conventions\ help\ to\ avoid\nsome\ common\ mistakes\ by\ prohibiting\ error-prone\ constructs\ such\ as\ building\ lists\ by\ hand\ instead\ of\ using\ the\ list\ building\ procedures.\ This\ document\ is\ based\ heavily\ on\ the\ ''Tcl/Tk\ Engineering\ Manual''\ \[http://tcl.sourceforge.net/engManual.pdf\]\ written\ by\ John\ Ousterhout.\ John's\ engineering\ manual\ specified\ the\ style\ of\ the\ C\ code\ used\ in\ the\ implementation\ of\ Tcl/Tk\ and\ many\ of\ its\ extensions.\ The\ manual\ is\ very\ valuable\ to\ the\ development\ of\ Tcl/Tk\ and\ is\ an\ important\ reason\ why\ Tcl\ is\ a\ relatively\ easy\ system\ to\ maintain.\ Deciding\ any\ style\ standard\ involves\ making\ trade-offs\ that\ are\ usually\ subjective.\ This\ standard\ was\ created\ in\ an\ iterative\ process\ involving\ the\ Tcl/Tk\ group\ at\ Sun\ Laboratories.\ I\ don't\ claim\ that\ these\ conventions\ are\ the\ best\ possible\ ones,\ but\ the\ exact\ conventions\ don't\ really\ make\ that\ much\ difference.\ The\ most\ important\ thing\ is\ that\ we\ all\ do\ things\ the\ same\ way.\n\nPlease\ write\ your\ code\ so\ that\ it\ conforms\ to\ the\ conventions\ from\ the\ very\ start.\ For\ example,\ don't\ write\ comment-free\ code\ on\ the\ assumption\ that\ you'll\ go\ back\ and\ put\ the\ comments\ in\ later\ once\ the\ code\ is\ working.\ This\ simply\ won't\ happen.\ Regardless\ of\ how\ngood\ your\ intentions\ are,\ when\ it\ comes\ time\ to\ go\ back\ and\ put\ in\ the\ comments\ you'll\ find\ that\ you\ have\ a\ dozen\ more\ important\ things\ to\ do\;\ as\ the\ body\ of\ uncommented\ code\ builds\ up,\ it\ will\ be\ harder\ and\ harder\ to\ work\ up\ the\ energy\ to\ go\ back\ and\ fix\ it\ all.\ One\ of\ the\ fundamental\ rules\ of\ software\ is\ that\ its\ structure\ only\ gets\ worse\ over\ time\;\ if\ you\ don't\ build\ it\ right\ to\ begin\ with,\ it\ will\ never\ get\ that\ way\ later.\n\nThe\ rest\ of\ this\ document\ consists\ of\ 8\ major\ parts.\ We\ start\ with\ Section\ 2\ which\ discusses\ executable\ files.\ Section\ 3\ discusses\ the\ overall\ structure\ of\ packages\ and\ namespaces.\ Section\ 4\ describes\ the\ structure\ of\ a\ Tcl\ code\ file\ and\ how\ to\ write\ procedure\ headers.\ Section\ 5\ describes\ the\ Tcl\ naming\ conventions.\ Section\ 6\ presents\ low-level\ coding\ conventions,\ such\ as\ how\ to\ indent\ and\ where\ to\ put\ curly\ braces.\ Section\ 7\ contains\ a\ collection\ of\ rules\ and\ suggestions\ for\ writing\ comments.\ Section\ 8\ describes\ how\ to\ write\ and\ maintain\ test\ suites.\ Section\ 9\ contains\ a\ few\ miscellaneous\ topics,\ such\ as\ keeping\ a\ change\ log.\n\n'''SECTION\ 2'''\n\n''Executable\ files''\n\nAn\ executable\ is\ a\ file,\ collection\ of\ files,\ or\ some\ other\ collection\ of\ Tcl\ code\ and\ necessary\ runtime\ environment.\ Often\ referred\ to\ as\ applications,\ an\ executable\ is\ simply\ what\ you\ run\ to\ start\ your\ program.\ The\ format\ and\ exact\ make\ up\ of\ an\ executable\ is\ platform-specific.\ At\ some\ point,\ however,\ a\ Tcl\ ''start-up\ script''\ will\ be\ evaluated.\ It\ is\ the\ start-up\ script\ that\ will\ bootstrap\ any\ Tcl\ based\ application.\ \n\nThe\ role\ of\ the\ start-up\ script\ is\ to\ load\ any\ needed\ packages,\ set\ up\ any\ non-package\ specific\ state,\ and\ finally\ start\ the\ Tcl\ application\ by\ calling\ routines\ inside\ a\ Tcl\ package.\ If\ the\ start-up\ script\ is\ more\ than\ a\ few\ lines\ it\ should\ probably\ be\ a\ package\ itself.\n\nThere\ are\ several\ ways\ to\ create\ executable\ scripts.\ Each\ major\ platform\ usually\ has\ a\ unique\ way\ of\ creating\ an\ executable\ application.\ Here\ is\ a\ brief\ description\ of\ how\ these\ applications\ should\ be\ created\ on\ each\ platform:\n\n1.\ The\ most\ common\ method\ for\ creating\ executable\ applications\ on\ UNIX\ platforms\ is\ the\ infamous\ '''#!'''\ (commonly\ called\ a\ ''shebang'')\ mechanism\ built\ into\ most\ shells.\ Unfortunately,\ the\ most\ common\ approach\ of\ just\ giving\ a\ path\ to\ wish\ is\ not\ recommended.\ \n\nDon't\ do:\n\n\ #!/usr/local/tclsh8.0\ -f\ \"\$0\"\ \"\$@\"\n\nThis\ method\ will\ not\ work\ if\ the\ file\ tclsh\ is\ another\ script\ that,\ for\ example,\ locates\ and\ starts\ the\ most\ recent\ version\ of\ Tcl.\ It\ also\ requires\ tclsh\ to\ be\ in\ a\ particular\ place,\ which\ makes\ the\ script\ less\ portable.\ Instead,\ the\ following\ method\ should\ be\ used\ which\ calls\ /bin/sh\ which\ will\ in\ turn\ exec\ the\ wish\ application.\n\n\ #!/bin/sh\n\ #\ the\ next\ line\ restarts\ using\ wish\ \\\n\ exec\ wish8.0\ \"\$0\"\ \"\$@\"\n\nThis\ example\ will\ actually\ locate\ the\ wish\ application\ in\ the\ user's\ path\ which\ can\ be\ very\ useful\ for\ developers.\ The\ backslash\ is\ recognized\ as\ part\ of\ a\ comment\ to\ ''sh'',\ but\ in\ Tcl\ the\ backslash\ continues\ the\ comment\ into\ the\ next\ line\ which\ keeps\ the\ exec\ command\ from\ executing\ again.\ However,\ more\ stable\ sites\ would\ probably\ want\ to\ include\ the\ full\ path\ instead\ of\ just\ wish.\ Note\ that\ the\ version\ number\ of\ the\ tclsh\ or\ wish\ interpreter\ is\ usually\ added\ to\ the\ end\ of\ the\ program\ name.\ This\ allows\ you\ use\ a\ specific\ version\ of\ Tcl.\ In\ addition,\ many\ sites\ include\ a\ link\ of\ wish\ to\ the\ latest\ version\ currently\ installed.\ This\ is\ useful\ if\ you\ know\ that\ your\ code\ will\ work\ on\ any\ version\ of\ Tcl.\n\nAnother\ common\ method\ seen\ is\ to\ use:\n\n\ #!/usr/bin/env\ tclsh\n\nThen\ you\ can\ just\ do\ a\ ''package\ require\ Tk''\ if\ \[Tk\]\ is\ actually\ needed.\ Your\ mileage\ may\ vary\ on\ using\ this\ one\ and\ you\ may\ run\ into\ trouble\ if\ you\ have\ multiple\ installs\ of\ \[Tcl/Tk\].\ \n\n2.\ On\ the\ Windows\ platform\ you\ only\ need\ to\ end\ a\ file\ with\ the\ ''.tcl''\ extension\ and\ the\ file\ will\ be\ run\ when\ the\ user\ double\ clicks\ on\ the\ file.\ This\ is,\ of\ course,\ assuming\ you\ have\ installed\ Tcl/Tk.\ Alternatively,\ you\ may\ create\ a\ .bat\ file\ which\ explicitly\ executes\ tclsh\ or\ wish\ with\ an\ absolute\ path\ to\ your\ start-up\ script.\ Please\ check\ the\ Windows\ documentation\ for\ more\ details\ about\ .bat\ files.\n\n3.\ The\ Macintosh\ platform,\ before\ MacOS\ X,\ didn't\ really\ have\ a\ notion\ of\ an\ executable\ Tcl\ file.\ One\ of\ the\ reasons\ for\ this\ was\ that,\ unlike\ UNIX\ or\ Windows,\ you\ could\ only\ run\ one\ instance\ of\ an\ application\ at\ a\ time.\ So\ instead\ of\ calling\ wish\ with\ a\ specific\ script\ to\ load,\ you\ had\ to\ create\ a\ copy\ of\ the\ wish\ application\ that\ was\ tied\ to\ our\ script.\ \n\nThe\ easiest\ way\ to\ do\ this\ was\ to\ use\ the\ application\ ''Drag&Drop\ Tclets''\ or\ the\ ''SpecTcl''\ GUI\ builder\ which\ could\ do\ this\ work\ for\ you.\ You\ could\ also\ do\ this\ by\ hand\ by\ putting\ the\ start-up\ script\ into\ a\ TEXT\ resource\ and\ naming\ it\ tclshrc\ -\ which\ ensured\ it\ got\ sourced\ on\ start-up.\ This\ could\ be\ done\ with\ ''ResEdit''\ (a\ tool\ provided\ by\ Apple)\ or\ other\ tools\ that\ manipulated\ resources.\ Additional\ scripts\ could\ also\ be\ placed\ in\ TEXT\ resource\ to\ make\ the\ application\ completely\ contained.\n\nHowever,\ Tcl's\ Macintosh\ support\ has\ moved\ to\ supporting\ only\ Mac\ OS\ X.\ \ So\ the\ above\ is\ relevant\ to\ older\ versions\ of\ Tcl.\n\n'''SECTION\ 3'''\n\n''Packages\ and\ namespaces''\n\nTcl\ applications\ consist\ of\ collections\ of\ ''packages''.\ Each\ package\ provides\ code\ to\ implement\ a\ related\ set\ of\ features.\ For\ example,\ Tcl\ itself\ is\ a\ package,\ as\ is\ Tk\;\ these\ packages\ happen\ to\ be\ implemented\ in\ both\ C\ and\ Tcl.\ Other\ packages\ are\ implemented\ completely\ in\ Tcl\ such\ as\ the\ http\ package\ included\ in\ the\ Tcl\ distribution.\ Packages\ are\ the\ units\ in\ which\ code\ is\ developed\ and\ distributed:\ a\ single\ package\ is\ typically\ developed\ by\ a\ single\ person\ or\ group\ and\ distributed\ as\ a\ unit.\ It\ is\ possible\ to\ combine\ many\ independently-developed\ packages\ into\ a\ single\ application\;\ packages\ should\ be\ designed\ with\ this\ in\ mind.\ The\ notion\ of\nnamespaces\ were\ created\ to\ help\ make\ this\ easier.\ Namespaces\ help\ to\ hide\ private\ aspects\ of\ packages\ and\ avoid\ name\ collisions.\ A\ package\ will\ generally\ export\ one\ public\ namespace\ which\ will\ include\ all\ state\ and\ routines\ that\ are\ associated\ with\ the\ package.\ A\ package\ should\ not\ contain\ any\ global\ variables\ or\ global\ procedures.\ Side\ effects\ when\ loading\ a\ package\ should\ be\ avoided.\ This\ document\ will\ focus\ on\ packages\ written\ entirely\ in\ Tcl.\ For\ a\ discussion\ of\ packages\ built\ in\ C\ or\ C\ and\ Tcl\ see\ the\ ''Tcl/Tk\ Engineering\ Manual''\[http://tcl.sourceforge.net/engManual.pdf\].\n\n'''SECTION\ 3.1'''\n\n''Package\ names''\n\nEach\ package\ should\ have\ a\ unique\ ''name''.\ The\ name\ of\ the\ package\ is\ used\ to\ identify\ the\ package.\ It\ is\ also\ used\ as\ the\ name\ of\ the\ namespace\ that\ the\ package\ exports.\ It\ is\ best\ to\ have\ a\ simple\ one\ word\ name\ in\ all\ lower-case\ like\ http.\ Multi-word\ names\ are\ okay\ as\ well.\ Additional\ words\ should\ just\ be\ concatenated\ with\ the\ first\ word\ but\ start\ with\ a\ capital\ letter\ like\ specMenu.\n\nComing\ up\ with\ a\ unique\ name\ for\ your\ package\ requires\ a\ collaborative\ component.\ For\ internal\ projects\ this\ is\ an\ easy\ task\ and\ can\ usually\ be\ decided\ among\ the\ management\ or\ principal\ engineers\ in\ your\ organization.\ For\ packages\ you\ wish\ to\ publish,\ however,\ you\nshould\ make\ an\ effort\ to\ make\ sure\ that\ an\ existing\ package\ isn't\ already\ using\ the\ same\ name\ you\ are.\ This\ can\ often\ be\ done\ by\ checking\ the\ comp.lang.tcl\ newsgroup\ or\ the\ standard\ Tcl\ ftp\ sites.\ It\ is\ also\ suggested\ (but\ not\ required)\ that\ you\ register\ your\ name\ on\ the\ NIST\ Identifier\ Collaboration\ Service\ (NICS).\ It\ is\ located\ at:\ http://pitch.nist.gov/nics\n\n'''SECTION\ 3.2'''\n\n''Version\ numbers''\n\nEach\ package\ has\ a\ two-part\ version\ number\ such\ as\ 7.4.\ The\ first\ number\ (7)\ is\ called\ the\ major\ version\ number\ and\ the\ second\ (4)\ is\ called\ the\ minor\ version\ number.\ The\ version\ number\ changes\ with\ each\ public\ release\ of\ the\ package.\ If\ a\ new\ release\ contains\ only\ bug\ fixes,\ new\ features,\ and\ other\ upwardly\ compatible\ changes,\ so\ that\ code\ and\ scripts\ that\ worked\ with\ the\ old\ version\ will\ also\ work\ with\ the\ new\ version,\ then\ the\ minor\ version\ number\ increments\ and\ the\ major\ version\ number\ stays\ the\ same\ (e.g.,\ from\ 7.4\ to\ 7.5).\ If\ the\ new\ release\ contains\ substantial\ incompatibilities,\ so\ that\ existing\ code\ and\ scripts\ will\ have\ to\ be\ modified\nto\ run\ with\ the\ new\ version,\ then\ the\ major\ version\ number\ increments\ and\ the\ minor\ version\ number\ resets\ to\ zero\ (e.g.,\ from\ 7.4\ to\ 8.0).\n\n'''SECTION\ 3.3'''\n\n''Package\ Namespaces''\n\nAs\ of\ version\ 8.0,\ Tcl\ supports\ namespaces\ to\ hide\ the\ internal\ structure\ of\ a\ package.\ This\ helps\ avoid\ name\ collisions\ and\ provides\ a\ simpler\ way\ to\ manage\ packages.\ All\ packages\ written\ for\ Tcl\ 8.0\ or\ newer\ should\ use\ namespaces.\ The\ name\ of\ the\ name\ space\ should\ be\ the\ same\ as\ the\ package\ name.\n\n'''SECTION\ 3.4'''\n\n''Structure''\n\nThere\ are\ a\ couple\ of\ ways\ to\ deploy\ a\ package\ of\ Tcl\ commands:\n\nA\ pkgIndex.tcl\ file\ is\ used\ to\ create\ ''packages''\ that\ can\ be\ loaded\ on\ demand\ by\ any\ Tcl\ script.\ Like\ a\ tclIndex\ file,\ a\ package\ specifies\ a\ set\ of\ Tcl\ and/or\ shared\ libraries\ that\ can\ be\ loaded\ when\ needed.\ A\ package,\ however,\ must\ be\ explicitly\ requested\ by\ using\ the\ package\ require\ command.\ You\ can\ use\ the\ pkg_mkIndex\ command\ to\ create\ a\ package\ index\ file\ for\ your\ use.\ In\ most\ cases,\ particularly\ in\ code\ you\ distribute\ to\ others,\ it\ is\ better\ to\ use\ a\ package\ instead\ of\ the\ tclIndex\ auto-loading\ mechanism.\n\n\ #\ specMenu.tcl\ --\n\ #\n\ ###Abstract\n\ #\ This\ file\ implements\ the\ Tcl\ code\ for\ creating\ and\n\ #\ managing\ the\ menus\ in\ the\ SpecTcl\ application.\n\ #\n\ #\ Copyright\ (c)\ 1994-1997\ Sun\ Microsystems,\ Inc.\n\ #\n\ ###Copyright\n\ #\ See\ the\ file\ \"license.terms\"\ for\ information\ on\ usage\ and\n\ #\ redistribution\ of\ this\ file,\ and\ for\ a\ DISCLAIMER\ OF\ ALL\ WARRANTIES.\n\ #\n\ ###Revision\ String\n\ #\ SCCS:\ %Z%\ %M%\ %I%\ %E%\ %U%\n\n\ ###\ Package\ Definition\ \n\ package\ require\ specTable\n\ package\ provide\ specMenu\ 1.0\n\n\ namespace\ eval\ specMenu\ \{\n\ \ \ \ \ namespace\ export\ addMenu\n\ \ \ \ \ array\ set\ menuData\ \{one\ two\ three\}\n\ \ \ \ \ ...\n\ \}\n\nFigure\ 1.\ An\ example\ of\ a\ header\ page.\n\nOn\ the\ Macintosh\ platform,\ shared\ libraries\ can\ be\ made\ into\ self\ contained\ packages.\ You\ simply\ need\ to\ add\ a\ TEXT\ resource\ with\ the\ name\ of\ pkgIndex.\ It\ will\ be\ treated\ in\ the\ exact\ same\ fashion\ as\ a\ pkgIndex.tcl\ file.\ The\ pkgIndex\ resource\ should\ have\ the\nsame\ format\ as\ the\ pkgIndex.tcl\ file.\n\n'''SECTION\ 4'''\n\n''How\ to\ organize\ a\ code\ file''\n\nEach\ source\ code\ file\ should\ either\ contain\ an\ entire\ application\ or\ a\ set\ of\ related\ procedures\ that\ make\ up\ a\ package\ or\ a\ another\ type\ of\ identifiable\ module,\ such\ as\ the\ implementation\ of\ the\ menus\ for\ your\ application,\ or\ a\ set\ of\ procedures\ to\ implement\ HTTP\ access.\ Before\ writing\ any\ code\ you\ should\ think\ carefully\ about\ what\ functions\ are\ to\ be\ provided\ and\ divide\ them\ into\ files\ in\ a\ logical\ way.\ The\ most\ manageable\ size\ for\ files\ is\ usually\ in\ the\ range\ of\ 500-2000\ lines.\ If\ a\ file\ gets\ much\ larger\ than\ this,\ it\ will\ be\ hard\ to\ remember\ everything\ that\ the\ file\ does.\ If\ a\ file\ is\ much\ shorter\ than\ this,\ then\ you\ may\ end\ up\ with\ too\ many\ files\ in\ a\ directory,\ which\ is\ also\ hard\ to\ manage.\n\n'''SECTION\ 4.1'''\n\n''The\ file\ header''\n\nThe\ first\ part\ of\ a\ code\ file\ is\ referred\ to\ as\ the\ header.\ It\ contains\ overall\ information\ that\ is\ relevant\ throughout\ the\ file.\ It\ consists\ of\ everything\ but\ the\ definitions\ of\ the\ file's\ procedures.\ The\ header\ typically\ has\ four\ parts,\ as\ shown\ in\ Figure\ 1:\n\n'''Abstract:'''\ The\ first\ few\ lines\ give\ the\ name\ of\ the\ file\ and\ a\ brief\ description\ of\ the\ overall\ functions\ provided\ by\ the\ file,\ just\ as\ in\ header\ files.\n\n'''Copyright\ notice:'''\ The\ notice\ protects\ ownership\ of\ the\ file.\ The\ copyright\ shown\ above\ is\ included\ in\ the\ Tcl\ and\ Tk\ sources.\ More\ product\ specific\ packages\ would\ probably\ have\ the\ words\ ''All\ rights\ reserved''\ included\ instead.\ If\ more\ than\ one\ entity\ contributed\ to\ the\ page\ they\ should\ each\ have\ a\ distinct\ copyright\ line.\n\n'''Revision\ string:'''\ The\ contents\ of\ this\ string\ are\ managed\ automatically\ by\ the\ source\ code\ control\ system\ for\ the\ file,\ such\ as\ RCS\ or\ SCCS\ (SCCS\ is\ used\ in\ the\ example\ in\ the\ figure).\ It\ identifies\ the\ file's\ current\ revision,\ date\ of\ last\ modification,\ and\ so\ on.\n\n'''Package\ definition:'''\ Also\ any\ require\ statements\ for\ other\ packages\ that\ this\ package\ depends\ on\ should\ be\ the\ first\ code\ in\ the\ file.\ Any\ global\ variables\ that\ are\ managed\ by\ this\ file\ should\ be\ declared\ at\ the\ top\ of\ the\ page.\ The\ name\ space\ definition\ should\ be\ next\ and\ the\ export\ list\ should\ be\ the\ first\ item\ in\ the\ namespace\ definition.\ Please\ structure\ your\ header\ pages\ in\ exactly\ the\ order\ given\ above\ and\ follow\ the\ syntax\ of\ Figure\ 1\ as\ closely\ as\ possible.\ The\ file\ fileHead.tcl\ provides\ a\ template\ for\ a\ header\npage.\n\n'''SECTION\ 4.2'''\n\n''Multi-file\ packages''\n\nSome\ packages\ may\ be\ too\ large\ to\ fit\ into\ one\ file.\ You\ may\ want\ to\ consider\ breaking\ the\ package\ into\ multiple\ independent\ packages.\ However,\ when\ that\ is\ not\ an\ option\ you\ need\ to\ make\ one\ of\ the\ files\ the\ ''primary''\ file.\ The\ primary\ file\ will\ include\ the\ complete\ export\ list\ and\ the\ definitions\ of\ all\ exported\ variables\ and\ procedures.\ The\ secondary\ files\ should\ only\ contain\ supporting\ routines\ to\ the\ primary\ file.\ It\ is\ important\ to\ construct\ your\ package\ in\ this\ manner\ or\ utilities\ like\ pkg_mkIndex\ will\ not\ work\ correctly.\ Finally,\ the\ header\ to\ the\ various\ files\ should\ make\ it\ clear\ which\ file\ is\ the\ primary\ file\ and\ which\ are\ supporting\ files.\n\n'''SECTION\ 4.3'''\n\n''Procedure\ headers''\n\nAfter\ the\ header\ you\ will\ have\ one\ or\ more\ procedures.\ Each\ procedure\ will\ begin\ with\ a\ ''procedure\ header''\ that\ gives\ overall\ documentation\ for\ the\ procedure,\ followed\ by\ the\ declaration\ and\ body\ for\ the\ procedure.\ See\ Figure\ Figure\ 2\ for\ an\ example.\ The\ header\ should\ contain\ everything\ that\ a\ caller\ of\ the\ procedure\ needs\ to\ know\ in\ order\ to\ use\ the\ procedure,\ and\ nothing\ else.\ It\ consists\ of\ three\ parts:\n\n'''Abstract:'''\ The\ first\ lines\ in\ the\ header\ give\ the\ procedure's\ name,\ followed\ by\ a\ brief\ description\ of\ what\ the\ procedure\ does.\ This\ should\ not\ be\ a\ detailed\ description\ of\ how\ the\ procedure\ is\ implemented,\ but\ rather\ a\ high-level\ summary\ of\ its\ overall\ function.\ In\ some\ cases,\ such\ as\ callback\ procedures,\ I\ recommend\ also\ describing\ the\ conditions\ under\ which\ the\ procedure\ is\ invoked\ and\ who\ calls\ the\ procedure.\n\n'''Arguments:'''\ This\ portion\ of\ the\ header\ describes\ the\ arguments\ that\ the\ procedure\ expects.\ Each\ argument\ should\ get\ at\ least\ one\ line.\ The\ comment\ should\ describe\ the\ expected\ type\ and\ describe\ it's\ function.\ Optional\ arguments\ should\ be\ pointed\ out\ and\ the\ default\ behavior\ of\ an\ unspecified\ argument\ should\ be\ mentioned.\ Comments\ for\ all\ of\ the\ arguments\ should\ line\ up\ on\ the\ same\ tab\ stop.\n\n\ #\ tcl::HistRedo\ --\n\ #\n\ #\ Fetch\ the\ previous\ or\ specified\ event,\ execute\ it,\ and\ then\n\ #\ replace\ the\ current\ history\ item\ with\ that\ event.\n\ #\n\ #\ Arguments:\n\ #\ event\ (optional)\ index\ of\ history\ item\ to\ redo.\ Defaults\n\ #\ to\ -1,\ which\ means\ the\ previous\ event.\n\ #\ Results:\n\ #\ The\ result\ is\ that\ of\ the\ command\ being\ redone.\ Also\ replaces\n\ #\ the\ current\ history\ list\ item\ with\ the\ one\ being\ redone.\n\ proc\ tcl::HistRedo\ \{\{event\ -1\}\}\ \{\n\ \ \ \ ...\n\ \}\n\ \nFigure\ 2.\ The\ header\ comments\ and\ declaration\ for\ a\ procedure.\n\n'''Results:'''\ The\ last\ part\ of\ the\ header\ describes\ the\ value\ returned\ by\ the\ procedure.\ The\ type\ and\ the\ intended\ use\ of\ the\ result\ should\ be\ described.\ This\ section\ should\ also\ mention\ any\ ''side\ effects''\ that\ are\ worth\ noting.\n\nThe\ file\ tclProcHead\ contains\ a\ template\ for\ a\ procedure\ header\ which\ should\ be\ used\ as\ a\ base\ for\ all\ new\ Tcl\ commands.\ Follow\ the\ syntax\ of\ Figure\ 2\ exactly\ (same\ indentation,\ double-dash\ after\ the\ procedure\ name,\ etc.).\n\n'''SECTION\ 4.4'''\n\n''Procedure\ declarations''\n\nThe\ procedure\ declaration\ should\ also\ follow\ exactly\ the\ syntax\ in\ Figure\ 2.\ Note\ that\ the\ procedure\ is\ defined\ outside\ the\ namespace\ command\ that\ defines\ the\ export\ list\ and\ namespace\ globals.\ The\ first\ line\ gives\ the\ proc\ keyword,\ the\ procedure\ name,\ and\ an\ argument\ list.\ If\ there\ are\ many\ arguments,\ they\ may\ spill\ onto\ additional\ lines\ (see\ Sections\ 6.1\ and\ 6.3\ for\ information\ about\ indentation).\n\n'''SECTION\ 4.5'''\n\n''Parameter\ order''\n\nProcedure\ parameters\ may\ be\ divided\ into\ three\ categories.\ In\ parameters\ only\ pass\ information\ into\ the\ procedure\ (either\ directly\ or\ by\ pointing\ to\ information\ that\ the\ procedure\ reads).\ Out\ parameters\ point\ to\ things\ in\ the\ caller's\ memory\ that\ the\ procedure\ modifies\ such\ as\ the\ name\ of\ a\ variable\ the\ procedure\ will\ modify.\ ''In-out''\ parameters\ do\ both.\ Below\ is\ a\ set\ of\ rules\ for\ deciding\ on\ the\ order\ of\ parameters\ to\ a\ procedure:\n\n1.\ Parameters\ should\ normally\ appear\ in\ the\ order\ in,\ in/out,\ out,\ except\ where\ overridden\ by\ the\ rules\ below.\n\n2.\ If\ an\ argument\ is\ actually\ a\ sub-command\ for\ the\ command\ than\ it\ should\ be\ the\ first\ argument\ of\ the\ command.\ \n\nFor\ example:\n\n\ proc\ graph::tree\ \{subCmd\ args\}\ \{\n\ \ \ \ \ switch\ \$subCmd\ \{\n\ \ \ \ \ \ \ \ \ add\ \{\n\ \ \ \ \ \ \ \ \ \ \ \ \ eval\ add_node\ \$args\n\ \ \ \ \ \ \ \ \ \}\n\ \ \ \ \ \ \ \ \ draw\ \{...\n\n3.\ If\ there\ is\ a\ group\ of\ procedures,\ all\ of\ which\ operate\ on\ an\ argument\ of\ a\ particular\ type,\nsuch\ as\ a\ file\ path\ or\ widget\ path,\ the\ argument\ should\ be\ the\ first\ argument\ to\ each\ of\ the\nprocedures\ (or\ after\ the\ sub-command\ argument).\n\n'''SECTION\ 4.6'''\n\n''Procedure\ bodies''\n\nThe\ body\ of\ a\ procedure\ follows\ the\ declaration.\ See\ Section\ 6\ for\ the\ coding\ conventions\ that\ govern\ procedure\ bodies.\ The\ curly\ braces\ enclosing\ the\ body\ should\ be\ on\ different\ lines,\ as\ shown\ in\ Figure\ Figure\ 2,\ even\ if\ the\ body\ of\ the\ procedure\ is\ empty.\n\n'''SECTION\ 5'''\ \n\n''Naming\ conventions''\n\nChoosing\ names\ is\ one\ of\ the\ most\ important\ aspects\ of\ programming.\ Good\ names\ clarify\ the\ function\ of\ a\ program\ and\ reduce\ the\ need\ for\ other\ documentation.\ Poor\ names\ result\ in\ ambiguity,\ confusion,\ and\ error.\ This\ section\ gives\ some\ general\ principles\ to\ follow\ when\ choosing\ names\ and\ lists\ specific\ rules\ for\ name\ syntax,\ such\ as\ capitalization.\n\n'''SECTION\ 5.1'''\n\n''General\ considerations''\n\nThe\ ideal\ variable\ name\ is\ one\ that\ instantly\ conveys\ as\ much\ information\ as\ possible\ about\ the\ purpose\ of\ the\ variable\ it\ refers\ to.\ When\ choosing\ names,\ play\ devil's\ advocate\ with\ yourself\ to\ see\ if\ there\ are\ ways\ that\ a\ name\ might\ be\ misinterpreted\ or\ confused.\ Here\ are\ some\ things\ to\ consider:\n\n1.\ Are\ you\ consistent?\ Use\ the\ same\ name\ to\ refer\ to\ the\ same\ thing\ everywhere.\ For\ example,\ within\ the\ code\ for\ handling\ standard\ bindings\ in\ Tk\ widgets,\ a\ standard\ name\ w\ is\ always\ used\ to\ refer\ to\ the\ window\ associated\ with\ the\ current\ event.\n\n2.\ If\ someone\ sees\ the\ name\ out\ of\ context,\ will\ they\ realize\ what\ it\ stands\ for,\ or\ could\ they\ confuse\ it\ with\ something\ else?\ For\ example,\ the\ procedure\ name\ buildStructure\ could\ get\ confused\ with\ some\ other\ part\ of\ the\ system.\ A\ name\ like\ buildGraphNode\nboth\ describes\ what\ part\ of\ the\ system\ it\ belongs\ to\ and\ what\ it\ is\ probably\ used\ for.\ \n\n3.\ Could\ this\ name\ be\ confused\ with\ some\ other\ name?\ For\ example,\ it's\ probably\ a\ mistake\ to\ have\ two\ variables\ str\ and\ string\ in\ the\ same\ procedure:\ it\ will\ be\ hard\ for\ anyone\ to\ remember\ which\ is\ which.\ Instead,\ change\ the\ names\ to\ reflect\ their\ functions.\ For\ example,\ if\ the\ strings\ are\ used\ as\ source\ and\ destination\ for\ a\ copy\ operation,\ name\ them\ src\ and\ dst.\n\n4.\ Is\ the\ name\ so\ generic\ that\ it\ doesn't\ convey\ any\ information?\ The\ variable\ str\ from\ the\ previous\ paragraph\ is\ an\ example\ of\ this\;\ changing\ its\ name\ to\ src\ makes\ the\ name\ less\ generic\ and\ hence\ conveys\ more\ information.\n\n'''SECTION\ 5.2'''\n\n''Basic\ syntax\ rules''\n\nBelow\ are\ some\ specific\ rules\ governing\ the\ syntax\ of\ names.\ Please\ follow\ the\ rules\ exactly,\ since\ they\ make\ it\ possible\ to\ determine\ certain\ properties\ of\ a\ variable\ just\ from\ its\ name.\ \n\n1.\ Exported\ names\ for\ both\ procedures\ and\ variables\ always\ start\ with\ a\ ''lower-case''\ letter.\ Procedures\ and\ variables\ that\ are\ meant\ only\ for\ use\ with\ in\ the\ current\ package\ or\ namespace\ should\ start\ with\ an\ ''upper-case''\ letter.\ We\ chose\ lower-case\ for\ the\ exported\ symbols\ because\ it\ is\ possible\ they\ may\ be\ commonly\ used\ from\ the\ command\ line\ and\ they\ should\ be\ easy\ to\ write.\ \n\nFor\ example:\n\n\ #\ CountNum\ is\ a\ private\ variable\n\ set\ CountNum\ 0\n\ #\ The\ function\ addWindow\ is\ public\n\ proc\ addWindow\ \{\}\ \{...\n\ #\ newWindow\ is\ a\ public\ interface\ in\ the\ spectcl\ namespace\n\ proc\ spectcl::newWindow\ \{\}\ \{...\n\ \n2.\ In\ multi-word\ names,\ the\ first\ letter\ of\ each\ trailing\ word\ is\ capitalized.\ Do\ not\ use\ underscores\ or\ dashes\ as\ separators\ between\ the\ words\ of\ a\ name.\n\n\ set\ numWindows\ 0\n\n3.\ Any\ variable\ whose\ value\ refers\ to\ another\ variable\ has\ a\ name\ that\ ends\ in\ Name.\ Furthermore,\ the\ name\ should\ also\ indicate\ what\ type\ of\ variable\ the\ name\ is\ referring\ to.\ These\ names\ are\ often\ used\ in\ arguments\ to\ procedures\ that\ are\ taking\ a\ name\ of\ a\ variable.\n\n\ proc\ foo::Bar\ \{arrayName\}\ \{\n\ \ \ \ upvar\ 1\ \$arrayName\ array\n\ \ \ \ ...\n\ \}\n\n4.\ Variables\ that\ hold\ Tcl\ code\ that\ will\ be\ evaled\ should\ have\ names\ ending\ in\ Script.\n\n\ proc\ log::eval\ \{logScript\}\ \{\n\ \ \ \ \ if\ \{\$Log::logOn\}\ \{\n\ \ \ \ \ \ \ \ \ set\ result\ \[catch\ \{eval\ \$logScript\}\ msg\]\n\ \ \ \ \ \ \ \ \ ...\n\n5.\ Variables\ that\ hold\ a\ partial\ Tcl\ command\ that\ must\ have\ additional\ arguments\ appended\ before\ being\ a\ valid\ script\ should\ have\ names\ ending\ in\ Cmd.\n\n\ foreach\ scrollCmd\ \$listScrollCmds\ \{\n\ \ \ \ \ eval\ \$scrollCmd\ \$args\n\ \}\n\n'''SECTION\ 6'''\n\n''Low-level\ coding\ conventions''\n\nThis\ section\ describes\ several\ low-level\ syntactic\ rules\ for\ writing\ Tcl\ code.\ These\ rules\ help\ to\ ensure\ that\ all\ of\ the\ Tcl\ code\ looks\ the\ same,\ and\ they\ prohibit\ a\ few\ confusing\ coding\ constructs.\n\n'''SECTION\ 6.1'''\n\n''Indents\ are\ 4\ spaces''\n\nEach\ level\ of\ indentation\ should\ be\ four\ spaces.\ There\ are\ ways\ to\ set\ 4-space\ indents\ in\ all\ of\ the\ most\ common\ editors.\ Be\ sure\ that\ your\ editor\ really\ uses\ four\ spaces\ for\ the\ indent,\ rather\ than\ just\ displaying\ tabs\ as\ four\ spaces\ wide\;\ if\ you\ use\ the\ latter\ approach\ then\ the\ indents\ will\ appear\ eight\ spaces\ wide\ in\ other\ editors.\n\n'''SECTION\ 6.2'''\n\n''Code\ comments\ occupy\ full\ lines''\n\nComments\ that\ document\ code\ should\ occupy\ full\ lines,\ rather\ than\ being\ tacked\ onto\ the\ ends\ of\ lines\ containing\ code.\ The\ reason\ for\ this\ is\ that\ side-by-side\ comments\ are\ hard\ to\ see,\ particularly\ if\ neighboring\ statements\ are\ long\ enough\ to\ overlap\ the\ \ side-by-side\ comments.\ Also\ it\ is\ easy\ to\ place\ comments\ in\ a\ place\ that\ could\ cause\ errors.\ Comments\ must\ have\ exactly\nthe\ structure\ shown\ in\ Figure\ 3,\ with\ a\ blank\ line\ above\ and\ below\ the\ comment.\ The\ leading\ blank\ line\ can\ be\ omitted\ if\ the\ comment\ is\ at\ the\ beginning\ of\ a\ block,\ as\ is\ the\ case\ in\ the\ second\ comment\ in\ Figure\ 3.\ Each\ comment\ should\ be\ indented\ to\ the\ same\ level\ as\ the\ surrounding\ code.\ Use\ proper\ English\ in\ comments:\ write\ complete\ sentences,\ capitalize\ the\ first\ word\ of\ each\ sentence,\ and\ so\non.\n\n\ #\ If\ we\ are\ running\ on\ the\ Macintosh\ platform\ then\ we\ can\n\ #\ assume\ that\ the\ sources\ are\ located\ in\ the\ resource\ fork\n\ #\ of\ our\ application,\ and\ we\ do\ not\ need\ to\ search\ for\ them.\n\ if\ \{\$tcl_platform(platform)\ ==\ \"macintosh\"\}\ \{\n\ \ \ \ \ return\n\ \}\n\ foreach\ dir\ \$dirList\ \{\n\ \ \ \ \ #\ If\ the\ source\ succeeds\ then\ we\ are\ done.\n\ \ \ \ \ if\ \{!\[catch\ \{source\ \[file\ join\ \$dir\ file.tcl\]\}\]\}\ \{\n\ \ \ \ \ \ \ \ \ break\n\ \ \ \ \ \}\n\ \}\n\n\nFigure\ 3.\ Comments\ in\ code\ have\ the\ form\ shown\ above,\ using\ full\ lines,\ with\ lined-up\ hashmarks,\ the\ comment\ takes\ at\ least\ a\ full\ \ \ \ \ \ \ line\ and\ blank\ separator\ lines\ around\ each\ comment\ (except\ that\ the\ leading\ blank\ line\ can\ be\ omitted\ if\ the\ comment\ is\ at\ the\ beginning\ of\ a\ code\ block)\ \n\ \ \n\n'''SECTION\ 6.3'''\n\n''Continuation\ lines\ are\ indented\ 8\ spaces\ ''\n\nYou\ should\ use\ continuation\ lines\ to\ make\ sure\ that\ no\ single\ line\ exceeds\ 80\ characters\ in\ length.\ Continuation\ lines\ should\ be\ indented\ 8\ spaces\ so\ that\ they\ won't\ be\ confused\ with\ an\ immediately-following\ nested\ block.\ Pick\ clean\ places\ to\ break\ your\ lines\ for\ continuation,\ so\ that\ the\ continuation\ doesn't\ obscure\ the\ structure\ of\ the\ statement.\ For\ example,\ if\ a\ procedure\ call\ requires\ continuation\ lines,\ try\ to\ avoid\ situations\ where\ a\ single\ argument\ spans\ multiple\ lines.\ If\ the\ test\ for\ an\ if\ or\ while\ command\ spans\ lines,\ try\ to\ make\ each\ line\ have\ the\ same\ nesting\ level\ of\ parentheses\ and/or\ brackets\ if\ possible.\ I\ try\ to\ start\ each\ continuation\ line\ with\ an\ operator\ such\ as\ *,\ &&,\ or\ ||\;\ this\ makes\ it\ clear\ that\ the\ line\ is\ a\ continuation,\ \nsince\ a\ new\ statement\ would\ never\ start\ with\ such\ an\ operator.\n\n'''SECTION\ 6.4'''\n\n''Only\ one\ command\ per\ line''\n\nYou\ should\ only\ have\ one\ Tcl\ command\ per\ line\ on\ the\ page.\ Do\ not\ use\ the\ semi-colon\ character\ to\ place\ multiple\ commands\ on\ the\ same\ line.\ This\ makes\ the\ code\ easier\ to\ read\ and\ helps\ with\ debugging.\n\n'''SECTION\ 6.5'''\n\n''Curly\ braces:\ \{\ goes\ at\ the\ end\ of\ a\ line''\n\nOpen\ curly\ braces\ can\ not\ appear\ on\ lines\ by\ themselves\ in\ Tcl.\ Instead,\ they\ should\ be\ placed\ at\ the\ end\ of\ the\ preceding\ line.\ Close\ curly\ braces\ are\ indented\ to\ the\ same\ level\ as\ the\ outer\ code,\ i.e.,\ four\ spaces\ less\ than\ the\ statements\ they\ enclose.\ However,\ you\ should\ ''always''\ use\ curly\ braces\ rather\ than\ some\ other\ list\ generating\ mechanism\ that\ will\ work\ in\ the\ Tcl\ language.\ This\ will\ help\ make\ code\ more\ readable,\ will\ avoid\ unwanted\ side\ effects,\ and\ in\ many\ cases\ will\ generate\ faster\ code\ with\ the\ Tcl\ compiler.\n\nControl\ structures\ should\ always\ use\ curly\ braces,\ even\ if\ there\ is\ only\ one\ statement\ in\nthe\ block.\ Thus\ you\ shouldn't\ write\ code\ like:\n\n\ if\ \{\$tcl_platform(platform)\ ==\ \"unix\"\}\ return\n\nbut\ rather:\n\n\ if\ \{\$tcl_platform(platform)\ ==\ \"unix\"\}\ \{\n\ \ \ \ \ return\n\ \}\n\nThis\ approach\ makes\ code\ less\ dense,\ but\ it\ avoids\ potential\ mistakes\ like\ unwanted\ Tcl\ substitutions.\ It\ also\ makes\ it\ easier\ to\ set\ breakpoints\ in\ a\ debugger,\ since\ it\ guarantees\ that\ each\ statement\ is\ on\ a\ separate\ line\ and\ can\ be\ named\ individually.\n\n'''SECTION\ 6.6'''\n\n''Parenthesize\ expressions''\n\nUse\ parentheses\ around\ each\ subexpression\ in\ an\ expression\ to\ make\ it\ absolutely\ clear\ what\ is\ the\ evaluation\ order\ of\ the\ expression\ (a\ reader\ of\ your\ code\ should\ not\ need\ to\ remember\ Tcl's\ precedence\ rules).\ \n\nFor\ example,\ don't\ type:\n\ \n\ if\ \{\$x\ >\ 22\ &&\ \$y\ <=\ 47\}\ ...\n\nInstead,\ type\ this:\n\ \n\ if\ \{(\$x\ >\ 22)\ &&\ (\$y\ <=\ 47)\}\ ...\n\n'''SECTION\ 6.7'''\n\n''Always\ use\ the\ return\ statement''\n\nYou\ should\ always\ explicitly\ use\ the\ return\ statement\ to\ return\ values\ from\ a\ Tcl\ procedure.\ By\ default\ Tcl\ will\ return\ the\ value\ of\ the\ last\ Tcl\ statement\ executed\ in\ a\ Tcl\ procedure\ as\ the\ return\ value\ of\ the\ procedure\ which\ often\ leads\ to\ confusion\ as\ to\ where\ the\ result\ is\ coming\ from.\ In\ addition,\ you\ should\ use\ a\ return\ statement\ with\ no\ argument\ for\ procedures\ whose\ results\ are\ ignored.\ Supplying\ this\ return\ will\ actually\ speed\ up\ your\ application\ with\ the\ new\ Tcl\ compiler.\ \n\nFor\ example,\ don't\ write\ code\ like\ this:\n\n\ proc\ foo\ \{x\ y\}\ \{\n\ \ \ \ \ if\ \{\$x\ <\ 0\}\ \{\n\ \ \ \ \ \ \ \ \ incr\ x\n\ \ \ \ \ \}\ else\ \{\n\ \ \ \ \ \ \ \ \ expr\ \$x\ +\ \$y\n\ \ \ \ \ \}\n\ \}\n\nBut\ rather,\ type\ this:\n\n\ proc\ foo\ \{x\ y\}\ \{\n\ \ \ \ \ if\ \{\$x\ <\ 0\}\ \{\n\ \ \ \ \ \ \ \ \ return\ \[incr\ x\]\n\ \ \ \ \ \}\ else\ \{\n\ \ \ \ \ \ \ \ \ return\ \[expr\ \$x\ +\ \$y\]\n\ \ \ \ \ \}\n\ \}\n\nFor\ Tcl\ procedures\ that\ have\ no\ return\ value\ a\ single\ return\ statement\ with\ no\ arguments\ is\ placed\ at\ the\ end\ of\ the\ procedure.\n\n'''SECTION\ 6.8'''\n\n''Switch\ statements''\n\nThe\ switch\ statement\ should\ be\ formatted\ as\ below.\ Always\ use\ the\ --\ option\ to\ avoid\ having\ the\ string\ be\ confused\ with\ an\ option.\ This\ can\ happen\ when\ the\ string\ is\ user\ generated.\ Comments\ can\ be\ added\ on\ the\ same\ line\ as\ the\ pattern\ to\ comment\ the\ pattern\ case.\ The\ comments\ for\ each\ case\ should\ line\ up\ on\ the\ same\ tab\ stop\ and\ must\ be\ within\ the\ braces.\ Note\ that\ this\ is\ an\ exception\ to\ the\ standard\ commenting\ conventions.\n\n\ switch\ -regexp\ --\ \$string\ \{\n\ \ \ \ \ plus\ -\n\ \ \ \ \ add\ \{\ \ \ \ \ \ \ \ #\ Do\ add\ task\n\ \ \ \ \ \ \ \ \ ...\n\ \ \ \ \ \}\n\ \ \ \ \ subtract\ \{\ \ \ #\ Do\ subtract\ case\n\ \ \ \ \ \ \ \ \ ...\n\ \ \ \ \ \}\n\ \ \ \ \ default\ \{\n\ \ \ \ \ \ \ \ \ ...\n\ \ \ \ \ \}\n\ \}\n\n'''SECTION\ 6.9'''\n\n''If\ statements''\n\nNever\ use\ the\ '''''then'''''\ word\ of\ an\ '''''if'''''\ statement.\ It\ is\ syntactic\ sugar\ that\ really\ isn't\ that\ useful.\ However,\ the\ else\ word\ should\ always\ be\ used\ as\ it\ does\ impart\ some\ semantic\ information\ and\ it\ is\ more\ like\ the\ C\ language.\ \n\nHere\ is\ an\ example:\n\ \n\ if\ \{\$x\ <\ 0\}\ \{\n\ \ \ \ \ ...\n\ \}\ elseif\ \{\$x\ ==\ 0\}\ \{\n\ \ \ \ \ ...\n\ \}\ else\ \{\n\ \ \ \ \ ...\n\ \}\n\n'''SECTION\ 7'''\n\n''Documenting\ code''\n\nThe\ purpose\ of\ documentation\ is\ to\ save\ time\ and\ reduce\ errors.\ Documentation\ is\ typically\ used\ for\ two\ purposes.\ First,\ people\ will\ read\ the\ documentation\ to\ find\ out\ how\ to\ use\ your\ code.\ For\ example,\ they\ will\ read\ procedure\ headers\ to\ learn\ how\ to\ call\ the\ procedures.\ Ideally,\ people\ should\ have\ to\ learn\ as\ little\ as\ possible\ about\ your\ code\ in\ order\ to\ use\ it\ correctly.\ Second,\ people\ will\ read\ the\ documentation\ to\ find\ out\ how\ your\ code\ works\ internally,\ so\ they\ can\ fix\ bugs\ or\ add\ new\ features\;\ again,\ good\ documentation\ will\ allow\ them\ to\ make\ their\ fixes\ or\ enhancements\ while\ learning\ the\ minimum\ possible\ about\ your\ code.\ More\ documentation\ isn't\ necessarily\ better:\ wading\ through\ pages\ of\ documentation\ may\ not\ be\ any\ easier\ than\ deciphering\ the\ code.\ Try\ to\ pick\ out\ the\ most\ important\ things\ that\ will\ help\ people\ to\ understand\ your\ code\ and\ focus\ on\ these\ in\ your\ documentation.\n\n'''SECTION\ 7.1'''\n\n''Document\ things\ with\ wide\ impact''\n\nThe\ most\ important\ things\ to\ document\ are\ those\ that\ affect\ many\ different\ pieces\ of\ a\ program.\ Thus\ it\ is\ essential\ that\ every\ procedure\ interface,\ every\ structure\ declaration,\ and\ every\ global\ variable\ be\ documented\ clearly.\ If\ you\ haven't\ documented\ one\ of\ these\ things\ it\ will\ be\ necessary\ to\ look\ at\ all\ the\ uses\ of\ the\ thing\ to\ figure\ out\ how\ it's\ supposed\ to\ work\;\ this\ will\ be\ntime-consuming\ and\ error-prone.\n\nOn\ the\ other\ hand,\ things\ with\ only\ local\ impact\ may\ not\ need\ much\ documentation.\ For\ example,\ in\ short\ procedures\ I\ don't\ usually\ have\ comments\ explaining\ the\ local\ variables.\ If\ the\ overall\ function\ of\ the\ procedure\ has\ been\ explained,\ and\ if\ there\ isn't\ much\ code\ in\ the\ procedure,\ and\ if\ the\ variables\ have\ meaningful\ names,\ then\ it\ will\ be\ easy\ to\ figure\ out\ how\ they\ are\ used.\ On\ the\ other\ hand,\ for\ long\ procedures\ with\ many\ variables\ I\ usually\ document\ the\ key\ variables.\ Similarly,\ when\ I\ write\ short\ procedures\ I\ don't\ usually\ have\ any\ comments\ in\ the\ procedure's\ code:\ the\ procedure\ header\ provides\ enough\ information\ to\ figure\ out\ what\ is\ going\ on.\ For\ long\ procedures\ I\ place\ a\ comment\ block\ before\ each\ major\ piece\ of\ the\ procedure\ to\ clarify\ the\ overall\ flow\ through\ the\ procedure.\n\n'''SECTION\ 7.2'''\n\n''Don't\ just\ repeat\ what's\ in\ the\ code''\n\nThe\ most\ common\ mistake\ I\ see\ in\ documentation\ (besides\ it\ not\ being\ there\ at\ all)\ is\ that\ it\ repeats\ what\ is\ already\ obvious\ from\ the\ code,\ such\ as\ this\ trivial\ (but\ exasperatingly\ common).\n\nexample:\n\n\ #\ Increment\ i.\n\ incr\ i\n\nDocumentation\ should\ provide\ higher-level\ information\ about\ the\ overall\ function\ of\ the\ code,\ helping\ readers\ to\ understand\ what\ a\ complex\ collection\ of\ statements\ really\ means.\ For\ example,\ the\ comment\n\n\ #\ Probe\ into\ the\ array\ to\ see\ if\ the\ symbol\ exists.\n\nis\ likely\ to\ be\ much\ more\ helpful\ than\ \n\n\ #\ Loop\ through\ every\ array\ index,\ get\ the\ third\ value\ of\ the\n\ #\ list\ in\ the\ content\ to\ determine\ if\ it\ has\ the\ symbol\ we\ are\n\ #\ looking\ for.\ Set\ the\ result\ to\ the\ symbol\ if\ we\ find\ it.\n\ \nEverything\ in\ this\ second\ comment\ is\ probably\ obvious\ from\ the\ code\ that\ follows\ it.\ Another\ thing\ to\ consider\ in\ your\ comments\ is\ word\ choice.\ Use\ different\ words\ in\ the\ comments\ than\ the\ words\ that\ appear\ in\ variable\ or\ procedure\ names.\ For\ example,\ the\ comment\n\n\ #\ SwapPanels\ --\n\ #\n\ #\ \ \ \ Swap\ the\ panels.\n\ #\ ...\n\nis\ not\ a\ very\ useful\ comment.\ Everything\ in\ the\ comment\ is\ already\ obvious\ from\ the\ procedure's\ name.\ Here\ is\ a\ much\ more\ useful\ comment:\n\n\ #\ SwapPanels\ --\n\ #\n\ #\ \ \ Unmap\ the\ current\ UI\ panel\ from\ the\ parent\ frame\ and\ replace\n\ #\ \ \ it\ with\ the\ newly\ specified\ frame.\ Make\ sure\ that\ the\ new\n\ #\ \ \ panel\ fits\ into\ the\ old\ frame\ and\ resize\ if\ needed.\n\ #\ ...\n\ \nThis\ comment\ tells\ why\ you\ might\ want\ to\ use\ the\ procedure,\ in\ addition\ to\ what\ it\ does,\ which\ makes\ the\ comment\ much\ more\ useful.\n\n'''SECTION\ 7.3'''\n\n''Document\ each\ thing\ in\ exactly\ one\ place''\n\nSystems\ evolve\ over\ time.\ If\ something\ is\ documented\ in\ several\ places,\ it\ will\ be\ hard\ to\ keep\ the\ documentation\ up\ to\ date\ as\ the\ system\ changes.\ Instead,\ try\ to\ document\ each\ major\ design\ decision\ in\ exactly\ one\ place,\ as\ near\ as\ possible\ to\ the\ code\ that\ implements\ the\ design\ decision.\ The\ principal\ documentation\ for\ each\ procedure\ goes\ in\ the\ procedure\ header.\ There's\ no\ need\ to\ repeat\ this\ information\ again\ in\ the\ body\ of\ the\ procedure\ (but\ you\ might\ have\ additional\ comments\ in\ the\ procedure\ body\ to\ fill\ in\ details\ not\ described\ in\ the\ procedure\ header).\ If\ a\ library\ procedure\ is\ documented\ thoroughly\ in\ a\ manual\ entry,\ then\ I\ may\ make\nthe\ header\ for\ the\ procedure\ very\ terse,\ simply\ referring\ to\ the\ manual\ entry.\ \n\nThe\ other\ side\ of\ this\ coin\ is\ that\ every\ major\ design\ decision\ needs\ to\ be\ documented\ at\ least\ once.\ If\ a\ design\ decision\ is\ used\ in\ many\ places,\ it\ may\ be\ hard\ to\ pick\ a\ central\ place\ to\ document\ it.\ Try\ to\ find\ a\ data\ structure\ or\ key\ procedure\ where\ you\ can\ place\ the\ main\ body\ of\ comments\;\ then\ reference\ this\ body\ in\ the\ other\ places\ where\ the\ decision\ is\ used.\ If\ all\ else\ fails,\ add\ a\ block\ of\ comments\ to\ the\ header\ page\ of\ one\ of\ the\ files\ implementing\ the\ decision.\n\n'''SECTION\ 7.4'''\n\n''Write\ clean\ code''\n\nThe\ best\ way\ to\ produce\ a\ well-documented\ system\ is\ to\ write\ clean\ and\ simple\ code.\ This\ way\ there\ won't\ be\ much\ to\ document.\ If\ code\ is\ clean,\ it\ means\ that\ there\ are\ a\ few\ simple\ ideas\ that\ explain\ its\ operation\;\ all\ you\ have\ to\ do\ is\ to\ document\ those\ key\ ideas.\ When\ writing\ code,\ ask\ yourself\ if\ there\ is\ a\ simple\ concept\ behind\ the\ code.\ If\ not,\ perhaps\ you\ should\ rethink\ the\ code.\ If\ it\ takes\ a\ lot\ of\ documentation\ to\ explain\ a\ piece\ of\ code,\ it\ is\ a\ sign\ that\ you\ haven't\ found\ a\ clean\ solution\ to\ the\ problem.\n\n'''SECTION\ 7.5'''\n\n''Document\ as\ you\ go''\n\nIt\ is\ extremely\ important\ to\ write\ the\ documentation\ as\ you\ write\ the\ code.\ It's\ very\ tempting\ to\ put\ off\ the\ documentation\ until\ the\ end\;\ after\ all,\ the\ code\ will\ change,\ so\ why\ waste\ time\ writing\ documentation\ now\ when\ you'll\ have\ to\ change\ it\ later?\ The\ problem\ is\ that\ the\ end\ never\ comes\ —\ there\ is\ always\ more\ code\ to\ write.\ Also,\ the\ more\ undocumented\ code\ that\ you\ accumulate,\ the\ harder\ it\ is\ to\ work\ up\ the\ energy\ to\ document\ it.\ So,\ you\ just\ write\ more\ undocumented\ code.\ I've\ seen\ many\ people\ start\ a\ project\ fully\ intending\ to\ go\ back\ at\ the\ end\ and\ write\ all\ the\ documentation,\ but\ I've\ never\ seen\ anyone\ actually\ do\ it.\n\nIf\ you\ do\ the\ documentation\ as\ you\ go,\ it\ won't\ add\ much\ to\ your\ coding\ time\ and\ you\ won't\ have\ to\ worry\ about\ doing\ it\ later.\ Also,\ the\ best\ time\ to\ document\ code\ is\ when\ the\ key\ ideas\ are\ fresh\ in\ your\ mind,\ which\ is\ when\ you're\ first\ writing\ the\ code.\ When\ I\ write\ new\ code,\ I\ write\ all\ of\ the\ header\ comments\ for\ a\ group\ of\ procedures\ before\ I\ fill\ in\ any\ of\ the\ bodies\ of\ the\ procedures.\ This\ way\ I\ can\ think\ about\ the\ overall\ structure\ and\ how\ the\ pieces\ fit\ together\ before\ getting\ bogged\ down\ in\ the\ details\ of\ individual\ procedures.\n\n'''SECTION\ 7.6'''\n\n''Document\ tricky\ situations''\n\nIf\ code\ is\ non-obvious,\ meaning\ that\ its\ structure\ and\ correctness\ depend\ on\ information\ that\ won't\ be\ obvious\ to\ someone\ reading\ it\ for\ the\ first\ time,\ be\ sure\ to\ document\ the\ non-obvious\ information.\ One\ good\ indicator\ of\ a\ tricky\ situation\ is\ a\ bug.\ If\ you\ discover\ a\ subtle\ property\ of\ your\ program\ while\ fixing\ a\ bug,\ be\ sure\ to\ add\ a\ comment\ explaining\ the\ problem\ and\ its\nsolution.\ Of\ course,\ it's\ even\ better\ if\ you\ can\ fix\ the\ bug\ in\ a\ way\ that\ eliminates\ the\ subtle\ behavior,\ but\ this\ isn't\ always\ possible.\n\n'''SECTION\ 8'''\n\n''Testing''\n\nOne\ of\ the\ environments\ where\ Tcl\ works\ best\ is\ for\ testing.\ While\ Tcl\ has\ traditionally\ been\ used\ for\ testing\ C\ code\ it\ is\ equally\ as\ good\ at\ testing\ other\ Tcl\ code.\ Whenever\ you\ write\ new\ code\ you\ should\ write\ Tcl\ test\ scripts\ to\ go\ with\ that\ code\ and\ save\ the\ tests\ in\ files\ so\ that\ they\ can\ be\ re-run\ later.\ Writing\ test\ scripts\ isn't\ as\ tedious\ as\ it\ may\ sound.\ If\ you're\ developing\nyour\ code\ carefully\ you're\ already\ doing\ a\ lot\ of\ testing\;\ all\ you\ need\ to\ do\ is\ type\ your\ test\ cases\ into\ a\ script\ file\ where\ they\ can\ be\ reused,\ rather\ than\ typing\ them\ interactively\ where\ they\ vanish\ after\ they're\ run.\n\n'''SECTION\ 8.1'''\n\n''Basics''\n\nTests\ should\ be\ organized\ into\ script\ files,\ where\ each\ file\ contains\ a\ collection\ of\ related\ tests.\ Individual\ tests\ should\ be\ based\ on\ the\ procedure\ test,\ just\ like\ in\ the\ Tcl\ and\ Tk\ test\ suites.\ Here\ are\ two\ examples:\n\n\ test\ expr-3.1\ \{floating-point\ operators\}\ \{\n\ \ \ \ \ expr\ 2.3*.6\n\ \}\ 1.38\n\n\ test\ expr-3.2\ \{floating-point\ operators\}\ \{unixOnly\}\ \{\n\ \ \ \ \ list\ \[catch\ \{expr\ 2.3/0\}\ msg\]\ \$msg\n\ \}\ \{1\ \{divide\ by\ zero\}\}\n\n''test''\ is\ a\ procedure\ defined\ in\ a\ script\ file\ named\ defs,\ which\ is\ sourced\ by\ each\ test\ file.\ ''test''\ takes\ four\ or\ five\ arguments:\ a\ test\ identifier,\ a\ string\ describing\ the\ test,\ an\ optional\ argument\ describing\ the\ conditions\ under\ which\ this\ test\ should\ run,\ a\ test\ script,\ and\ the\ expected\ result\ of\ the\ script.\ test\ evaluates\ the\ script\ and\ checks\ to\ be\ sure\ that\ it\ produces\nthe\ expected\ result.\ If\ not,\ it\ prints\ a\ message\ like\ the\ following:\n\n\ ====\ expr-3.1\ floating-point\ operators\n\ ====\ Contents\ of\ test\ case:\n\ \ \ \ \ expr\ 2.3*.6\n\ ====\ Result\ was:\n\ 1.39\n\ ----\ Result\ should\ have\ been:\n\ 1.38\n\ ----\ expr-3.1\ FAILED\n\nTo\ run\ a\ set\ of\ tests,\ you\ start\ up\ the\ application\ and\ source\ a\ test\ file.\ If\ all\ goes\ well\ no\ messages\ appear\;\ if\ errors\ are\ detected,\ a\ message\ is\ printed\ for\ each\ error.\ \n\nThe\ test\ identifier,\ such\ as\ expr-3.1,\ is\ printed\ when\ errors\ occur.\ It\ can\ be\ used\ to\ search\ a\ test\ script\ to\ locate\ the\ source\ for\ a\ failed\ test.\ The\ first\ part\ of\ the\ identifier,\ such\ as\ expr,\ should\ be\ the\ same\ as\ the\ name\ of\ the\ test\ file,\ except\ that\ the\ test\ file\ should\ have\ a\ .test\ extension,\ such\ as\ expr.test.\ The\ two\ numbers\ allow\ you\ to\ divide\ your\ tests\ into\ groups.\ The\ tests\ in\ a\ particular\ group\ (e.g.,\ all\ the\ expr-3.n\ tests)\ relate\ to\ a\ single\ sub-feature,\ such\ as\ a\ single\ procedure.\ The\ tests\ should\ appear\ in\ the\ test\ file\ in\ the\ same\ order\ as\ their\ numbers.\n\nThe\ test\ name,\ such\ as\ ''floating-point\ operators'',\ is\ printed\ when\ errors\ occur.\ It\ provides\ human-readable\ information\ about\ the\ general\ nature\ of\ the\ test.\n\nBefore\ writing\ tests\ I\ suggest\ that\ you\ look\ over\ some\ of\ the\ test\ files\ for\ Tcl\ and\ Tk\ to\ see\ how\ they\ are\ structured.\ You\ may\ also\ want\ to\ look\ at\ the\ README\ files\ in\ the\ Tcl\ and\ Tk\ test\ directories\ to\ learn\ about\ additional\ features\ that\ provide\ more\ verbose\ output\ or\ restrict\ the\ set\ of\ tests\ that\ are\ run.\n\n'''SECTION\ 8.2'''\n\n''Organizing\ tests''\n\nOrganize\ your\ tests\ to\ match\ the\ code\ being\ tested.\ The\ best\ way\ to\ do\ this\ is\ to\ have\ one\ test\ file\ for\ each\ source\ code\ file,\ with\ the\ name\ of\ the\ test\ file\ derived\ from\ the\ name\ of\ the\ source\ file\ in\ an\ obvious\ way\ (e.g.\ http.test\ contains\ tests\ for\ the\ code\ in\ http.tcl).\ Within\ the\ test\ file,\ have\ one\ group\ of\ tests\ for\ each\ procedure\ (for\ example,\ all\ the\ http-3.n\ tests\ in\ http.test\ are\ for\ the\ procedure\ http::geturl).\ The\ order\ of\ the\ tests\ within\ a\ group\ should\ be\ the\ same\ as\ the\ order\ of\ the\ code\ within\ the\ procedure.\ This\ approach\ makes\ it\ easy\ to\ find\ the\ tests\ for\ a\ particular\ piece\ of\ code\ and\ add\ new\ tests\ as\ the\ code\ changes.\ The\ Tcl\ test\ suite\ was\ written\ a\ long\ time\ ago\ and\ uses\ a\ different\ style\ where\ there\ is\ one\ file\ for\ each\ Tcl\ command\ or\ group\ of\ related\ commands,\ and\ the\ tests\ are\ grouped\ within\ the\ file\ by\ sub-command\ or\ features.\ In\ this\ approach\ the\ relationship\ between\ tests\ and\ particular\ pieces\ of\ code\ is\ much\ less\ obvious,\ so\ it\ is\ harder\ to\ maintain\ the\ tests\ as\ the\ code\nevolves.\ I\ don't\ recommend\ using\ this\ approach\ for\ new\ tests.\n\n'''SECTION\ 8.3'''\n\n''Coverage''\n\nWhen\ writing\ tests,\ you\ should\ attempt\ to\ exercise\ every\ line\ of\ source\ code\ at\ least\ once.\ There\ will\ be\ occasionally\ be\ code\ that\ you\ can't\ exercise,\ such\ as\ code\ that\ exits\ the\ application,\ but\ situations\ like\ this\ are\ rare.\ You\ may\ find\ it\ hard\ to\ exercise\ some\ pieces\ of\ code\ because\ existing\ Tcl\ commands\ don't\ provide\ fine\ enough\ control\ to\ generate\ all\ the\ possible\ execution\ paths.\ In\ situations\ like\ this,\ write\ one\ or\ more\ new\ Tcl\ commands\ just\ for\ testing\ purposes.\ It's\ much\ better\ to\ test\ a\ facility\ directly\ then\ to\ rely\ on\ some\ side\ effect\ for\ testing\ that\ may\ change\ over\ time.\ Use\ a\ similar\ approach\ in\ your\ own\ code,\ where\ you\ have\ an\ extra\nfile\ with\ additional\ commands\ for\ testing.\n\nIt's\ not\ sufficient\ just\ to\ make\ sure\ each\ line\ of\ code\ is\ executed\ by\ your\ tests.\ In\ addition,\ your\ tests\ must\ discriminate\ between\ code\ that\ executes\ correctly\ and\ code\ that\ isn't\ correct.\ For\ example,\ write\ tests\ to\ make\ sure\ that\ the\ then\ and\ else\ branches\ of\ each\ if\ statement\ are\ taken\ under\ the\ correct\ conditions.\ For\ a\ loop,\ run\ different\ tests\ to\ make\ the\ loop\ execute\ zero\ times,\ one\ time,\ and\ two\ or\ more\ times.\ If\ a\ piece\ of\ code\ removes\ an\ element\ from\ a\ list,\ try\ cases\ where\ the\ element\ to\ be\ removed\ is\ the\ first\ element,\ last\ element,\ only\ element,\ and\ neither\ first\ element\ nor\ last.\ Try\ to\ find\ all\ the\ places\ where\ different\ pieces\ of\ code\ interact\ in\ unusual\ ways,\ and\ exercise\ the\ different\ possible\ interactions.\n\n'''SECTION\ 8.4'''\n\n''Fixing\ bugs''\n\nWhenever\ you\ find\ a\ bug\ in\ your\ code\ it\ means\ that\ the\ test\ suite\ wasn't\ complete.\ As\ part\ of\ fixing\ the\ bug,\ you\ should\ add\ new\ tests\ that\ detect\ the\ presence\ of\ the\ bug.\ I\ recommend\ writing\ the\ tests\ after\ you've\ located\ the\ bug\ but\ ''before''\ you\ fix\ it.\ That\ way\ you\ can\ verify\ that\ the\ bug\ happens\ before\ you\ implement\ the\ fix\ and\ the\ bug\ doesn't\ happen\ afterwards,\ so\ you'll\ know\ you've\ really\ fixed\ something.\ Use\ bugs\ to\ refine\ your\ testing\ approach:\ think\ about\ what\ you\ might\ be\ able\ to\ do\ differently\ when\ you\ write\ tests\ in\ the\ future\ to\ keep\ bugs\ like\ this\ one\ from\ going\ undetected.\n\n'''SECTION\ 8.5'''\n\n''Tricky\ features''\n\nI\ also\ use\ tests\ as\ a\ way\ of\ illustrating\ the\ need\ for\ tricky\ code.\ If\ a\ piece\ of\ code\ has\ an\ unusual\ structure,\ and\ particularly\ if\ the\ code\ is\ hard\ to\ explain,\ I\ try\ to\ write\ additional\ tests\ that\ will\ fail\ if\ the\ code\ is\ implemented\ in\ the\ obvious\ manner\ instead\ of\ using\ the\ tricky\ approach.\ This\ way,\ if\ someone\ comes\ along\ later,\ doesn't\ understand\ the\ documentation\ for\ the\ code,\ decides\ the\ complex\ structure\ is\ unnecessary,\ and\ changes\ the\ code\ back\ to\ the\ simple\ (but\ incorrect)\ form,\ the\ test\ will\ fail\ and\ the\ person\ will\ be\ able\ to\ use\ the\ test\ to\ understand\ why\ the\ code\ needs\ to\ be\ the\ way\ it\ is.\ Illustrative\ tests\ are\ not\ a\ substitute\ for\ good\ndocumentation,\ but\ they\ provide\ a\ useful\ addition.\n\n'''SECTION\ 8.6'''\n\n''Test\ independence''\n\nTry\ to\ make\ tests\ independent\ of\ each\ other,\ so\ that\ each\ test\ can\ be\ understood\ in\ isolation.\ For\ example,\ one\ test\ shouldn't\ depend\ on\ commands\ executed\ in\ a\ previous\ test.\ This\ is\ important\ because\ the\ test\ suite\ allows\ tests\ to\ be\ run\ selectively:\ if\ the\ tests\ depend\ on\ each\ other,\ then\ false\ errors\ will\ be\ reported\ when\ someone\ runs\ a\ few\ of\ the\ tests\ without\ the\ others.\ \n\nFor\ convenience,\ you\ may\ execute\ a\ few\ statements\ in\ the\ test\ file\ to\ set\ up\ a\ test\ configuration\ and\ then\ run\ several\ tests\ based\ on\ that\ configuration.\ If\ you\ do\ this,\ put\ the\ setup\ code\ outside\ the\ calls\ to\ the\ test\ procedure\ so\ it\ will\ always\ run\ even\ if\ the\ individual\ tests\ aren't\ run.\ I\ suggest\ keeping\ a\ very\ simple\ structure\ consisting\ of\ setup\ followed\ by\ a\ group\ of\ tests.\ Don't\ perform\ some\ setup,\ run\ a\ few\ tests,\ modify\ the\ setup\ slightly,\ run\ a\ few\ more\ tests,\ modify\ the\ setup\ again,\ and\ so\ on.\ If\ you\ do\ this,\ it\ will\ be\ hard\ for\ people\ to\ figure\ out\ what\ the\ setup\ is\ at\ any\ given\ point\ and\ when\ they\ add\ tests\ later\ they\ are\ likely\ to\ break\ the\ setup.\n\n'''SECTION\ 9'''\n\n''Miscellaneous''\n\n'''SECTION\ 9.1'''\n\n''Porting\ Issues''\n\nWriting\ portable\ scripts\ in\ Tcl\ is\ actually\ quite\ easy\ as\ Tcl\ itself\ is\ quite\ portable.\ However,\ issues\ do\ arise\ that\ may\ require\ writing\ platform\ specific\ code.\ To\ conditionalize\ your\ code\ in\ this\ manner\ you\ should\ use\ the\ tcl_platform\ array\ to\ determine\ platform\ specific\ differences.\ You\ should\ avoid\ the\ use\ of\ the\ env\ variable\ unless\ you\ have\ already\ determined\ the\ platform\ you\ are\ running\ on\ via\ the\ tcl_platform\ array.\ \n\nAs\ Tcl/Tk\ has\ become\ more\ cross\ platform\ we\ have\ added\ commands\ that\ aid\ in\ making\ your\ code\ more\ portable.\ The\ most\ common\ porting\ mistakes\ result\ from\ assumptions\ about\ file\ names\ and\ locations.\ To\ avoid\ such\ mistakes\ always\ use\ the\ file\ join\ command\ and\nlist\ commands\ so\ that\ you\ will\ handle\ different\ file\ separation\ characters\ or\ spaces\ in\ file\ names.\ In\ Tk,\ you\ should\ always\ use\ provided\ high\ level\ dialog\ boxes\ instead\ or\ creating\ your\ own.\ The\ font\ and\ menu\ commands\ has\ also\ be\ revamped\ to\ make\ writing\ cross-platform\ code\ easier.\n\n'''SECTION\ 9.2'''\n\n''Changes\ files''\n\nEach\ package\ should\ contain\ a\ file\ named\ changes\ that\ keeps\ a\ log\ of\ all\ significant\ changes\ made\ to\ the\ package.\ The\ changes\ file\ provides\ a\ way\ for\ users\ to\ find\ out\ what's\ new\ in\ each\ new\ release,\ what\ bugs\ have\ been\ fixed,\ and\ what\ compatibility\ problems\ might\ be\ introduced\ by\ the\ new\ release.\ The\ changes\ file\ should\ be\ in\ chronological\ order.\ Just\ add\ short\ blurbs\ to\ it\ each\ time\ you\ make\ a\ change.\ Here\ is\ a\ sample\ from\ the\ Tk\ changes\ file:\n\n\ 5/19/94\ (bug\ fix)\ Canvases\ didn't\ generate\ proper\ Postscript\ for\ stippled\ text.\ (RJ)\n\ 5/20/94\ (new\ feature)\ Added\ \"bell\"\ command\ to\ ring\ the\ display's\ bell.\ (JO)\n\ 5/26/94\ (feature\ removed)\ Removed\ support\ for\ \"fill\"\ justify\ mode\ from\ Tk_GetJustify.\ (SS)\n\n***\ POTENTIAL\ INCOMPATIBILITY\ ***\nThe\ entries\ in\ the\ changes\ file\ can\ be\ relatively\ terse\;\ once\ someone\ finds\ a\ change\ that\ is\ relevant,\ they\ can\ always\ go\ to\ the\ manual\ entries\ or\ code\ to\ find\ out\ more\ about\ it.\ Be\ sure\ to\ highlight\ changes\ that\ cause\ compatibility\ problems,\ so\ people\ can\ scan\ the\ changes\ file\ quickly\ to\ locate\ the\ incompatibilities.\ Also\ be\ sure\ to\ add\ your\ initials\ to\ the\ entry\ so\ that\ people\ scanning\ the\ log\ will\ know\ who\ made\ a\ particular\ change.\n\n----\n\[Lars\ H\]:\ It\ says\ above\ ''Continuation\ lines\ are\ indented\ 8\ spaces''.\ I\ can't\ recall\ ever\ seeing\ such\ indents\ for\ continuations\;\ 2\ spaces\ seem\ far\ more\ common...\ Is\ this\ a\ typo\ or\ a\ guideline\ that\ the\ community\ ignored?\n\n\[LV\]\ To\ be\ honest,\ the\ primary\ place\ that\ the\ style\ guidelines\ is\nexpected\ to\ be\ followed\ is\ the\ core\ distribution.\ \ However,\ the\nguidelines\ are\ useful\ to\ any\ other\ Tcl\ developer\ as\ well.\nAlso\ note\ that,\ as\ ''guidelines''\ these\ are\ just\ suggestions\ that\ were\nmade,\ sometimes\ arbitrarily,\ so\ that\ people\ who\ want\ or\ need\ a\ standard\nhave\ something\ against\ which\ to\ work.\ \ To\ say\ ''ignored''\ makes\ it\nsound\ as\ some\ sort\ of\ rebellion\;\ I\ suspect\ it\ is\ more\ a\ matter\ of\ many\ndevelopers\ not\ having\ read\ the\ guidelines,\ or\ at\ least\ not\ recently.\n\n''\[escargo\]\ 9\ Apr\ 2005''\ -\ Personally\ I\ find\ indents\ of\ 2\ too\ few\ and\ 8\ too\ many.\ I\ usually\ use\ 4\nand\ get\ support\ for\ this\ from\ \[emacs\]\ and\ \[ASED\].\n\n\[RLH\]\ -\ Ruby\ is\ the\ only\ language\ that\ I\ have\ seen\ that\ has\ ''standardized''\ on\ 2\ spaces.\ I\ agree\ on\ 4\ and\ if\ you\ noticed\ all\ the\ examples\ are\ indented\ with\ 4\ spaces\ as\ well.\n\n\[Lars\ H\]:\ Note\ to\ '''RLH''',\ and\ possibly\ '''escargo'''\ also:\ The\ issue\ was\ ''continuation''\ indentations,\ i.e.,\ those\ following\ a\ backslash-newline\ combination.\ AFAICT\ there\ are\ no\ examples\ of\ these\ above.\ \[RLH\]\ -\ Ah!\ Then\ '''is'''\ 8\ the\ norm?\ \[escargo\]\ -\ I\ just\ ran\ tests\;\ \[emacs\]\ in\ Tcl\ mode\ did\ 4\;\ \[ASED\]\ does\ 8.\ I\ don't\ tend\nto\ change\ things\ manually,\ so\ I\ live\ with\ whatever\ the\ editor\ supports.\ \ \[aricb\]:\ FWIW,\ the\ default\ Tcl\ mode\ on\ my\ Emacs\ installation\ on\ Windows\ (20.7.1)\ indents\ continuation\ lines\ 8\ spaces.\n\n\[AET\]\ 11apr05\ I\ seem\ to\ remember\ (it's\ a\ long\ time\ since\ I\ read\ this)\ that\ the\ point\ was\ to\ have\ DOUBLE\ the\ indent\ (whatever\ you\ use)\ for\ line\ continuation\ to\ differentiate\ them\ from\ one-line\ statements.\ \ \n\n\[HE\]\ 23Jul06\ I\ prefer\ the\ use\ of\ tabs\ to\ indent\ lines.\ This\ has\ some\ advantages\ at\ least\ for\ me:\n\ \ \ *\ Use\ the\ identwidth\ you\ like:\ Most\ editors\ use\ tabs\ 8\ space\ wide.\ If\ the\ editor\ let\ you\ justify\ the\ tabs\ width,\ you\ can\ display\ the\ indents\ like\ you\ want.\ For\ example\ on\ win32\ I\ often\ use\ notepad\ with\ tabs\ =\ 8\ spaces.\ On\ \[pocketPC\]\ I\ prefer\ tabs\ =\ 2\ spaces.\n\ \ \ *\ Tabs\ saves\ memory.\ A\ file\ with\ 500\ lines\ has\ 500\ and\ more\ indents.\ 500\ Indents\ =\ 4\ *\ 500\ spaces\ =\ 2000\ characters.\ With\ tabs\ this\ are\ only\ 500\ characters\ (500\ indents\ =\ 500\ tabs).\ (\[NullGravy\]\ Long\ ago\ this\ made\ sense\ but\ in\ an\ era\ of\ 1Tb\ disks\ for\ <\ £200\ it\ is\ a\ false\ economy.)\n\nI\ use\ the\ following\ rules\ for\ tabs:\n\ \ \ *\ Use\ tabs\ for\ indent.\ \n\ \ \ *\ Fot\ every\ level\ of\ indent\ use\ one\ tab.\n\ \ \ *\ Every\ line\ continuation\ ident\ for\ two\ level.\n\ \ \ *\ Indents\ inside\ comments:\ A\ hashmark\ followed\ by\ tabs.\n\ \ \ *\ Never\ use\ tabs\ inside\ a\ line.\ To\ align\ codefragments\ use\ spaces.\ Reason:\ If\ the\ reader\ use\ an\ alternative\ tabswidth,\ the\ alignment\ is\ broken.\n\nBy\ the\ way.\ The\ original\ tcl/tk\ code\ uses\ a\ mix\ of\ spaces\ and\ tabs\ for\ indent:\n\ \ \ *\ First\ indent\ =\ 4\ spaces\n\ \ \ *\ Second\ indent\ =\ 1\ tab\n\ \ \ *\ Third\ indent\ =\ 1\ tab\ and\ 4\ spaces\n\ \ \ *\ Fourth\ indent\ =\ 2\ tabs\n\ \ \ *\ ...\n\n\[NullGravy\]\ Which\ is\ why\ it\ is\ always\ better\ to\ map\ tabs\ to\ spaces\ on\ input\ -\ otherwise\ someone\ with\ tabs\ set\ at\ anything\ other\ than\ 8\ will\ not\ see\ the\ code\ line\ up\ properly.This\ was\ the\ way\ people\ used\ to\ set\ up\ vi\ for\ the\ space\ reasons\ given\ above).\ In\ my\ experience\ the\ system\ breaks\ down\ badly\ when\ you\ start\ modifying\ code\ obtained\ from\ different\ sources\ with\ different\ ideas\ about\ how\ wide\ a\ tab\ is.\ Also\ the\ most\ basic\ viewers\ (e.g.\ cat\ or\ type)\ will\ ALWAYS\ see\ tabs\ as\ 8\ characters.\n\n----\n\[Agent\]:\ I\ like\ the\ idea\ of\ naming\ commands\ with\ hyphens,\ e.g.\n\ proc\ parse-arguments\ \{\}\ \{\ ...\ \}\nto\ distinguish\ them\ from\ variables\ (which\ of\ course\ must\ use\ underscores\ or\ camel-case).\n\n\[DKF\]:\ Except\ that\ nearly\ all\ valid\ procedure\ names\ are\ also\ valid\ variable\ names\ (the\ exception\ are\ things\ that\ work\ out\ to\ be\ invalid\ array\ references).\ OK,\ the\ '''\$...'''\ syntax\ can't\ handle\ them\ all,\ but\ \[set\]\ can.\n\n\[AMG\]:\ What\ about\ single-word\ command\ names?\ \ (That\ would\ be\ the\ majority,\ in\ my\ experience.)\ \ And\ why\ is\ it\ necessary\ to\ make\ a\ distinction?\ \ It\ is\ not\ only\ legal\ but\ also\ sometimes\ useful\ to\ give\ a\ command\ and\ a\ variable\ the\ same\ name.\ \ See\ \[Gadgets\].\n\n\[Agent\]:\ Well,\ a\ style\ guide\ isn't\ a\ set\ of\ absolute\ rules.\ If\ you\ find\ it\ useful\ to\ give\ a\ command\ and\ variable\ the\ same\ name,\ then\ do\ so.\ Single-word\ command\ names\ are\ usually\ imperative-case\ verbs,\ which\ distinguish\ themselves\ from\ variables.\ \[DKF\],\ I\ don't\ understand\ your\ point.\ Variables\ ''can''\ be\ named\ using\ hyphens\ or\ whatever,\ but\ ''should''\ only\ be\ named\ with\ camel-case\ and\ underscores\ so\ they\ are\ easy\ to\ use\ with\ '''\$'''.\ But,\ as\ commands\ aren't\ used\ with\ '''\$''',\ command\ naming\ need\ not\ restrict\ itself\ to\ camel-case\ and\ underscores,\ so\ that\ affords\ an\ way\ to\ distinguish\ between\ them.\n\n----\n'''CHANGES\ TO\ DOCUMENT'''\n\n\ \ \ *\ \[RLH\]\ -\ Does\ the\ SpecTcl\ stuff\ need\ to\ be\ stripped\ out\ and\ changed?\n\n''Example:''\ 2005-04-11:\ Changed\ the\ blah\ blah\ section\ to\ more\ accurately\ reflect\ the\ current\ accepted\ practice\ with\ foobar.\ \[RLH\]\n\n2005-April-12:\ Changed\ Section\ 2,\ executable\ files\ so\ that\ the\ info\ about\ Macintosh\ is\ couched\ in\ terms\ of\ the\ days\ before\ MacOS\ X.\n\n2005-April-14:\ Did\ some\ formatting\ to\ make\ it\ more\ like\ the\ original.\n\n----\n'''\[hmk\]\ -\ 2010-05-25\ 17:50:45'''\n\nThe\ \"file\ header\"\ in\ this\ wiki\ article\ appears\ to\ be\ different\ from\ this\ article\ from\ 2009:\ http://www.tcl.tk/cgi-bin/tct/tip/352.html\ which\ is\ the\ correct\ way?\n\n======\n\n<<categories>>\ Category\ Tutorial regexp2} CALL {my render {Tcl Style Guide} Coding\ style\ is\ often\ the\ subject\ of\ heated\ debates,\ of\ almost\nreligious\ fervor.\ \ But\ the\ bottom\ line\ is\ that\ consistent\ \ncoding,\ following\ a\ reasonably\ well\ thought\ out\ style,\nwill\ produce\ more\ readable,\ maintainable,\ and\ bug-free\ncode\ than\ arbitrary\ free-form\ off-the-cuff\ programming.\n\nTcl\ is\ no\ different\ in\ this\ respect.\ \ All\ Tcl\ application\ and\nlibrary\ code\ can\ benefit\ from\ following\ simple\ guidelines\ that\nwill\ make\ the\ code\ more\ readable\ and\ reliable.\ \ Some\ nice\ndocumentation\ is\ already\ available\ in\ the\ form\ of\ the\n''Tcl\ Style\ Guide''\ by\ Ray\ Johnson,\ which\ is\ available\ at\nhttp://www.tcl.tk/doc/styleGuide.pdf\ .\ \ This\ \ndocument\ describes\ high\ level\ conventions\ for\ writing\ scripts\nsuch\ as\ naming\ conventions\ and\ file\ organization.\ The\ following\ document\ outline\ is\ a\ wikified\ version\ of\ that\ PDF.\n\n----\n\n'''Document\ Outline'''\n\ \ \ 1\ Introduction\n\ \ \ 2\ Executable\ files\n\ \ \ 3\ Packages\ and\ namespaces\n\ \ \ 3.1\ Package\ names\n\ \ \ 3.2\ Version\ numbers\n\ \ \ 3.3\ Package\ Namespaces\n\ \ \ 3.4\ Structure\n\ \ \ 4\ How\ to\ organize\ a\ code\ file\n\ \ \ 4.1\ The\ file\ header\n\ \ \ 4.2\ Multi-file\ packages\n\ \ \ 4.3\ Procedure\ headers\n\ \ \ 4.4\ Procedure\ declarations\n\ \ \ 4.5\ Parameter\ order\n\ \ \ 4.6\ Procedure\ bodies\n\ \ \ 5\ Naming\ conventions\n\ \ \ 5.1\ General\ considerations\n\ \ \ 5.2\ Basic\ syntax\ rules\n\ \ \ 6\ Low-level\ coding\ conventions\n\ \ \ 6.1\ Indents\ are\ 4\ spaces\n\ \ \ 6.2\ Code\ comments\ occupy\ full\ lines\n\ \ \ 6.3\ Continuation\ lines\ are\ indented\ 8\ spaces\n\ \ \ 6.4\ Only\ one\ command\ per\ line\n\ \ \ 6.5\ Curly\ braces:\ \{\ goes\ at\ the\ end\ of\ a\ line\n\ \ \ 6.6\ Parenthesize\ expressions\n\ \ \ 6.7\ Always\ use\ the\ return\ statement\n\ \ \ 6.8\ Switch\ statements\n\ \ \ 6.9\ If\ statements\ \n\ \ \ 7\ Documenting\ code\n\ \ \ 7.1\ Document\ things\ with\ wide\ impact\n\ \ \ 7.2\ Don't\ just\ repeat\ what's\ in\ the\ code\n\ \ \ 7.3\ Document\ each\ thing\ in\ exactly\ one\ place\ \n\ \ \ 7.4\ Write\ clean\ code\ \n\ \ \ 7.5\ Document\ as\ you\ go\ \n\ \ \ 7.6\ Document\ tricky\ situations\ \n\ \ \ 8\ Testing\ \n\ \ \ 8.1\ Basics\ \n\ \ \ 8.2\ Organizing\ tests\ \n\ \ \ 8.3\ Coverage\ \n\ \ \ 8.4\ Fixing\ bugs\ \n\ \ \ 8.5\ Tricky\ features\ \n\ \ \ 8.6\ Test\ independence\ \n\ \ \ 9\ Miscellaneous\ \n\ \ \ 9.1\ Porting\ Issues\ \n\ \ \ 9.2\ Changes\ files\n\n'''SECTION\ 1'''\n\n''Introduction''\n\nThis\ is\ a\ manual\ for\ people\ who\ are\ developing\ Tcl\ code\ for\ Wish\ or\ any\ other\ Tcl\ application.\ It\ describes\ a\ set\ of\ conventions\ for\ writing\ code\ and\ the\ associated\ test\ scripts.\ There\ are\ three\ reasons\ for\ the\ conventions.\ First,\ the\ conventions\ ensure\ that\ certain\ important\ things\ get\ done\;\ for\ example,\ every\ procedure\ must\ have\ documentation\ that\ describes\ each\ of\ its\ arguments\ and\ its\ result,\ and\ there\ must\ exist\ test\ scripts\ that\ exercise\ every\ line\ of\ code.\ Second,\ the\ conventions\ guarantee\ that\ all\ of\ the\ Tcl\ and\ Tk\ code\ has\ a\ uniform\ style.\ This\ makes\ it\ easier\ for\ us\ to\ use,\ read,\ and\ maintain\ each\ other's\ code.\ Third,\ the\ conventions\ help\ to\ avoid\nsome\ common\ mistakes\ by\ prohibiting\ error-prone\ constructs\ such\ as\ building\ lists\ by\ hand\ instead\ of\ using\ the\ list\ building\ procedures.\ This\ document\ is\ based\ heavily\ on\ the\ ''Tcl/Tk\ Engineering\ Manual''\ \[http://tcl.sourceforge.net/engManual.pdf\]\ written\ by\ John\ Ousterhout.\ John's\ engineering\ manual\ specified\ the\ style\ of\ the\ C\ code\ used\ in\ the\ implementation\ of\ Tcl/Tk\ and\ many\ of\ its\ extensions.\ The\ manual\ is\ very\ valuable\ to\ the\ development\ of\ Tcl/Tk\ and\ is\ an\ important\ reason\ why\ Tcl\ is\ a\ relatively\ easy\ system\ to\ maintain.\ Deciding\ any\ style\ standard\ involves\ making\ trade-offs\ that\ are\ usually\ subjective.\ This\ standard\ was\ created\ in\ an\ iterative\ process\ involving\ the\ Tcl/Tk\ group\ at\ Sun\ Laboratories.\ I\ don't\ claim\ that\ these\ conventions\ are\ the\ best\ possible\ ones,\ but\ the\ exact\ conventions\ don't\ really\ make\ that\ much\ difference.\ The\ most\ important\ thing\ is\ that\ we\ all\ do\ things\ the\ same\ way.\n\nPlease\ write\ your\ code\ so\ that\ it\ conforms\ to\ the\ conventions\ from\ the\ very\ start.\ For\ example,\ don't\ write\ comment-free\ code\ on\ the\ assumption\ that\ you'll\ go\ back\ and\ put\ the\ comments\ in\ later\ once\ the\ code\ is\ working.\ This\ simply\ won't\ happen.\ Regardless\ of\ how\ngood\ your\ intentions\ are,\ when\ it\ comes\ time\ to\ go\ back\ and\ put\ in\ the\ comments\ you'll\ find\ that\ you\ have\ a\ dozen\ more\ important\ things\ to\ do\;\ as\ the\ body\ of\ uncommented\ code\ builds\ up,\ it\ will\ be\ harder\ and\ harder\ to\ work\ up\ the\ energy\ to\ go\ back\ and\ fix\ it\ all.\ One\ of\ the\ fundamental\ rules\ of\ software\ is\ that\ its\ structure\ only\ gets\ worse\ over\ time\;\ if\ you\ don't\ build\ it\ right\ to\ begin\ with,\ it\ will\ never\ get\ that\ way\ later.\n\nThe\ rest\ of\ this\ document\ consists\ of\ 8\ major\ parts.\ We\ start\ with\ Section\ 2\ which\ discusses\ executable\ files.\ Section\ 3\ discusses\ the\ overall\ structure\ of\ packages\ and\ namespaces.\ Section\ 4\ describes\ the\ structure\ of\ a\ Tcl\ code\ file\ and\ how\ to\ write\ procedure\ headers.\ Section\ 5\ describes\ the\ Tcl\ naming\ conventions.\ Section\ 6\ presents\ low-level\ coding\ conventions,\ such\ as\ how\ to\ indent\ and\ where\ to\ put\ curly\ braces.\ Section\ 7\ contains\ a\ collection\ of\ rules\ and\ suggestions\ for\ writing\ comments.\ Section\ 8\ describes\ how\ to\ write\ and\ maintain\ test\ suites.\ Section\ 9\ contains\ a\ few\ miscellaneous\ topics,\ such\ as\ keeping\ a\ change\ log.\n\n'''SECTION\ 2'''\n\n''Executable\ files''\n\nAn\ executable\ is\ a\ file,\ collection\ of\ files,\ or\ some\ other\ collection\ of\ Tcl\ code\ and\ necessary\ runtime\ environment.\ Often\ referred\ to\ as\ applications,\ an\ executable\ is\ simply\ what\ you\ run\ to\ start\ your\ program.\ The\ format\ and\ exact\ make\ up\ of\ an\ executable\ is\ platform-specific.\ At\ some\ point,\ however,\ a\ Tcl\ ''start-up\ script''\ will\ be\ evaluated.\ It\ is\ the\ start-up\ script\ that\ will\ bootstrap\ any\ Tcl\ based\ application.\ \n\nThe\ role\ of\ the\ start-up\ script\ is\ to\ load\ any\ needed\ packages,\ set\ up\ any\ non-package\ specific\ state,\ and\ finally\ start\ the\ Tcl\ application\ by\ calling\ routines\ inside\ a\ Tcl\ package.\ If\ the\ start-up\ script\ is\ more\ than\ a\ few\ lines\ it\ should\ probably\ be\ a\ package\ itself.\n\nThere\ are\ several\ ways\ to\ create\ executable\ scripts.\ Each\ major\ platform\ usually\ has\ a\ unique\ way\ of\ creating\ an\ executable\ application.\ Here\ is\ a\ brief\ description\ of\ how\ these\ applications\ should\ be\ created\ on\ each\ platform:\n\n1.\ The\ most\ common\ method\ for\ creating\ executable\ applications\ on\ UNIX\ platforms\ is\ the\ infamous\ '''#!'''\ (commonly\ called\ a\ ''shebang'')\ mechanism\ built\ into\ most\ shells.\ Unfortunately,\ the\ most\ common\ approach\ of\ just\ giving\ a\ path\ to\ wish\ is\ not\ recommended.\ \n\nDon't\ do:\n\n\ #!/usr/local/tclsh8.0\ -f\ \"\$0\"\ \"\$@\"\n\nThis\ method\ will\ not\ work\ if\ the\ file\ tclsh\ is\ another\ script\ that,\ for\ example,\ locates\ and\ starts\ the\ most\ recent\ version\ of\ Tcl.\ It\ also\ requires\ tclsh\ to\ be\ in\ a\ particular\ place,\ which\ makes\ the\ script\ less\ portable.\ Instead,\ the\ following\ method\ should\ be\ used\ which\ calls\ /bin/sh\ which\ will\ in\ turn\ exec\ the\ wish\ application.\n\n\ #!/bin/sh\n\ #\ the\ next\ line\ restarts\ using\ wish\ \\\n\ exec\ wish8.0\ \"\$0\"\ \"\$@\"\n\nThis\ example\ will\ actually\ locate\ the\ wish\ application\ in\ the\ user's\ path\ which\ can\ be\ very\ useful\ for\ developers.\ The\ backslash\ is\ recognized\ as\ part\ of\ a\ comment\ to\ ''sh'',\ but\ in\ Tcl\ the\ backslash\ continues\ the\ comment\ into\ the\ next\ line\ which\ keeps\ the\ exec\ command\ from\ executing\ again.\ However,\ more\ stable\ sites\ would\ probably\ want\ to\ include\ the\ full\ path\ instead\ of\ just\ wish.\ Note\ that\ the\ version\ number\ of\ the\ tclsh\ or\ wish\ interpreter\ is\ usually\ added\ to\ the\ end\ of\ the\ program\ name.\ This\ allows\ you\ use\ a\ specific\ version\ of\ Tcl.\ In\ addition,\ many\ sites\ include\ a\ link\ of\ wish\ to\ the\ latest\ version\ currently\ installed.\ This\ is\ useful\ if\ you\ know\ that\ your\ code\ will\ work\ on\ any\ version\ of\ Tcl.\n\nAnother\ common\ method\ seen\ is\ to\ use:\n\n\ #!/usr/bin/env\ tclsh\n\nThen\ you\ can\ just\ do\ a\ ''package\ require\ Tk''\ if\ \[Tk\]\ is\ actually\ needed.\ Your\ mileage\ may\ vary\ on\ using\ this\ one\ and\ you\ may\ run\ into\ trouble\ if\ you\ have\ multiple\ installs\ of\ \[Tcl/Tk\].\ \n\n2.\ On\ the\ Windows\ platform\ you\ only\ need\ to\ end\ a\ file\ with\ the\ ''.tcl''\ extension\ and\ the\ file\ will\ be\ run\ when\ the\ user\ double\ clicks\ on\ the\ file.\ This\ is,\ of\ course,\ assuming\ you\ have\ installed\ Tcl/Tk.\ Alternatively,\ you\ may\ create\ a\ .bat\ file\ which\ explicitly\ executes\ tclsh\ or\ wish\ with\ an\ absolute\ path\ to\ your\ start-up\ script.\ Please\ check\ the\ Windows\ documentation\ for\ more\ details\ about\ .bat\ files.\n\n3.\ The\ Macintosh\ platform,\ before\ MacOS\ X,\ didn't\ really\ have\ a\ notion\ of\ an\ executable\ Tcl\ file.\ One\ of\ the\ reasons\ for\ this\ was\ that,\ unlike\ UNIX\ or\ Windows,\ you\ could\ only\ run\ one\ instance\ of\ an\ application\ at\ a\ time.\ So\ instead\ of\ calling\ wish\ with\ a\ specific\ script\ to\ load,\ you\ had\ to\ create\ a\ copy\ of\ the\ wish\ application\ that\ was\ tied\ to\ our\ script.\ \n\nThe\ easiest\ way\ to\ do\ this\ was\ to\ use\ the\ application\ ''Drag&Drop\ Tclets''\ or\ the\ ''SpecTcl''\ GUI\ builder\ which\ could\ do\ this\ work\ for\ you.\ You\ could\ also\ do\ this\ by\ hand\ by\ putting\ the\ start-up\ script\ into\ a\ TEXT\ resource\ and\ naming\ it\ tclshrc\ -\ which\ ensured\ it\ got\ sourced\ on\ start-up.\ This\ could\ be\ done\ with\ ''ResEdit''\ (a\ tool\ provided\ by\ Apple)\ or\ other\ tools\ that\ manipulated\ resources.\ Additional\ scripts\ could\ also\ be\ placed\ in\ TEXT\ resource\ to\ make\ the\ application\ completely\ contained.\n\nHowever,\ Tcl's\ Macintosh\ support\ has\ moved\ to\ supporting\ only\ Mac\ OS\ X.\ \ So\ the\ above\ is\ relevant\ to\ older\ versions\ of\ Tcl.\n\n'''SECTION\ 3'''\n\n''Packages\ and\ namespaces''\n\nTcl\ applications\ consist\ of\ collections\ of\ ''packages''.\ Each\ package\ provides\ code\ to\ implement\ a\ related\ set\ of\ features.\ For\ example,\ Tcl\ itself\ is\ a\ package,\ as\ is\ Tk\;\ these\ packages\ happen\ to\ be\ implemented\ in\ both\ C\ and\ Tcl.\ Other\ packages\ are\ implemented\ completely\ in\ Tcl\ such\ as\ the\ http\ package\ included\ in\ the\ Tcl\ distribution.\ Packages\ are\ the\ units\ in\ which\ code\ is\ developed\ and\ distributed:\ a\ single\ package\ is\ typically\ developed\ by\ a\ single\ person\ or\ group\ and\ distributed\ as\ a\ unit.\ It\ is\ possible\ to\ combine\ many\ independently-developed\ packages\ into\ a\ single\ application\;\ packages\ should\ be\ designed\ with\ this\ in\ mind.\ The\ notion\ of\nnamespaces\ were\ created\ to\ help\ make\ this\ easier.\ Namespaces\ help\ to\ hide\ private\ aspects\ of\ packages\ and\ avoid\ name\ collisions.\ A\ package\ will\ generally\ export\ one\ public\ namespace\ which\ will\ include\ all\ state\ and\ routines\ that\ are\ associated\ with\ the\ package.\ A\ package\ should\ not\ contain\ any\ global\ variables\ or\ global\ procedures.\ Side\ effects\ when\ loading\ a\ package\ should\ be\ avoided.\ This\ document\ will\ focus\ on\ packages\ written\ entirely\ in\ Tcl.\ For\ a\ discussion\ of\ packages\ built\ in\ C\ or\ C\ and\ Tcl\ see\ the\ ''Tcl/Tk\ Engineering\ Manual''\[http://tcl.sourceforge.net/engManual.pdf\].\n\n'''SECTION\ 3.1'''\n\n''Package\ names''\n\nEach\ package\ should\ have\ a\ unique\ ''name''.\ The\ name\ of\ the\ package\ is\ used\ to\ identify\ the\ package.\ It\ is\ also\ used\ as\ the\ name\ of\ the\ namespace\ that\ the\ package\ exports.\ It\ is\ best\ to\ have\ a\ simple\ one\ word\ name\ in\ all\ lower-case\ like\ http.\ Multi-word\ names\ are\ okay\ as\ well.\ Additional\ words\ should\ just\ be\ concatenated\ with\ the\ first\ word\ but\ start\ with\ a\ capital\ letter\ like\ specMenu.\n\nComing\ up\ with\ a\ unique\ name\ for\ your\ package\ requires\ a\ collaborative\ component.\ For\ internal\ projects\ this\ is\ an\ easy\ task\ and\ can\ usually\ be\ decided\ among\ the\ management\ or\ principal\ engineers\ in\ your\ organization.\ For\ packages\ you\ wish\ to\ publish,\ however,\ you\nshould\ make\ an\ effort\ to\ make\ sure\ that\ an\ existing\ package\ isn't\ already\ using\ the\ same\ name\ you\ are.\ This\ can\ often\ be\ done\ by\ checking\ the\ comp.lang.tcl\ newsgroup\ or\ the\ standard\ Tcl\ ftp\ sites.\ It\ is\ also\ suggested\ (but\ not\ required)\ that\ you\ register\ your\ name\ on\ the\ NIST\ Identifier\ Collaboration\ Service\ (NICS).\ It\ is\ located\ at:\ http://pitch.nist.gov/nics\n\n'''SECTION\ 3.2'''\n\n''Version\ numbers''\n\nEach\ package\ has\ a\ two-part\ version\ number\ such\ as\ 7.4.\ The\ first\ number\ (7)\ is\ called\ the\ major\ version\ number\ and\ the\ second\ (4)\ is\ called\ the\ minor\ version\ number.\ The\ version\ number\ changes\ with\ each\ public\ release\ of\ the\ package.\ If\ a\ new\ release\ contains\ only\ bug\ fixes,\ new\ features,\ and\ other\ upwardly\ compatible\ changes,\ so\ that\ code\ and\ scripts\ that\ worked\ with\ the\ old\ version\ will\ also\ work\ with\ the\ new\ version,\ then\ the\ minor\ version\ number\ increments\ and\ the\ major\ version\ number\ stays\ the\ same\ (e.g.,\ from\ 7.4\ to\ 7.5).\ If\ the\ new\ release\ contains\ substantial\ incompatibilities,\ so\ that\ existing\ code\ and\ scripts\ will\ have\ to\ be\ modified\nto\ run\ with\ the\ new\ version,\ then\ the\ major\ version\ number\ increments\ and\ the\ minor\ version\ number\ resets\ to\ zero\ (e.g.,\ from\ 7.4\ to\ 8.0).\n\n'''SECTION\ 3.3'''\n\n''Package\ Namespaces''\n\nAs\ of\ version\ 8.0,\ Tcl\ supports\ namespaces\ to\ hide\ the\ internal\ structure\ of\ a\ package.\ This\ helps\ avoid\ name\ collisions\ and\ provides\ a\ simpler\ way\ to\ manage\ packages.\ All\ packages\ written\ for\ Tcl\ 8.0\ or\ newer\ should\ use\ namespaces.\ The\ name\ of\ the\ name\ space\ should\ be\ the\ same\ as\ the\ package\ name.\n\n'''SECTION\ 3.4'''\n\n''Structure''\n\nThere\ are\ a\ couple\ of\ ways\ to\ deploy\ a\ package\ of\ Tcl\ commands:\n\nA\ pkgIndex.tcl\ file\ is\ used\ to\ create\ ''packages''\ that\ can\ be\ loaded\ on\ demand\ by\ any\ Tcl\ script.\ Like\ a\ tclIndex\ file,\ a\ package\ specifies\ a\ set\ of\ Tcl\ and/or\ shared\ libraries\ that\ can\ be\ loaded\ when\ needed.\ A\ package,\ however,\ must\ be\ explicitly\ requested\ by\ using\ the\ package\ require\ command.\ You\ can\ use\ the\ pkg_mkIndex\ command\ to\ create\ a\ package\ index\ file\ for\ your\ use.\ In\ most\ cases,\ particularly\ in\ code\ you\ distribute\ to\ others,\ it\ is\ better\ to\ use\ a\ package\ instead\ of\ the\ tclIndex\ auto-loading\ mechanism.\n\n\ #\ specMenu.tcl\ --\n\ #\n\ ###Abstract\n\ #\ This\ file\ implements\ the\ Tcl\ code\ for\ creating\ and\n\ #\ managing\ the\ menus\ in\ the\ SpecTcl\ application.\n\ #\n\ #\ Copyright\ (c)\ 1994-1997\ Sun\ Microsystems,\ Inc.\n\ #\n\ ###Copyright\n\ #\ See\ the\ file\ \"license.terms\"\ for\ information\ on\ usage\ and\n\ #\ redistribution\ of\ this\ file,\ and\ for\ a\ DISCLAIMER\ OF\ ALL\ WARRANTIES.\n\ #\n\ ###Revision\ String\n\ #\ SCCS:\ %Z%\ %M%\ %I%\ %E%\ %U%\n\n\ ###\ Package\ Definition\ \n\ package\ require\ specTable\n\ package\ provide\ specMenu\ 1.0\n\n\ namespace\ eval\ specMenu\ \{\n\ \ \ \ \ namespace\ export\ addMenu\n\ \ \ \ \ array\ set\ menuData\ \{one\ two\ three\}\n\ \ \ \ \ ...\n\ \}\n\nFigure\ 1.\ An\ example\ of\ a\ header\ page.\n\nOn\ the\ Macintosh\ platform,\ shared\ libraries\ can\ be\ made\ into\ self\ contained\ packages.\ You\ simply\ need\ to\ add\ a\ TEXT\ resource\ with\ the\ name\ of\ pkgIndex.\ It\ will\ be\ treated\ in\ the\ exact\ same\ fashion\ as\ a\ pkgIndex.tcl\ file.\ The\ pkgIndex\ resource\ should\ have\ the\nsame\ format\ as\ the\ pkgIndex.tcl\ file.\n\n'''SECTION\ 4'''\n\n''How\ to\ organize\ a\ code\ file''\n\nEach\ source\ code\ file\ should\ either\ contain\ an\ entire\ application\ or\ a\ set\ of\ related\ procedures\ that\ make\ up\ a\ package\ or\ a\ another\ type\ of\ identifiable\ module,\ such\ as\ the\ implementation\ of\ the\ menus\ for\ your\ application,\ or\ a\ set\ of\ procedures\ to\ implement\ HTTP\ access.\ Before\ writing\ any\ code\ you\ should\ think\ carefully\ about\ what\ functions\ are\ to\ be\ provided\ and\ divide\ them\ into\ files\ in\ a\ logical\ way.\ The\ most\ manageable\ size\ for\ files\ is\ usually\ in\ the\ range\ of\ 500-2000\ lines.\ If\ a\ file\ gets\ much\ larger\ than\ this,\ it\ will\ be\ hard\ to\ remember\ everything\ that\ the\ file\ does.\ If\ a\ file\ is\ much\ shorter\ than\ this,\ then\ you\ may\ end\ up\ with\ too\ many\ files\ in\ a\ directory,\ which\ is\ also\ hard\ to\ manage.\n\n'''SECTION\ 4.1'''\n\n''The\ file\ header''\n\nThe\ first\ part\ of\ a\ code\ file\ is\ referred\ to\ as\ the\ header.\ It\ contains\ overall\ information\ that\ is\ relevant\ throughout\ the\ file.\ It\ consists\ of\ everything\ but\ the\ definitions\ of\ the\ file's\ procedures.\ The\ header\ typically\ has\ four\ parts,\ as\ shown\ in\ Figure\ 1:\n\n'''Abstract:'''\ The\ first\ few\ lines\ give\ the\ name\ of\ the\ file\ and\ a\ brief\ description\ of\ the\ overall\ functions\ provided\ by\ the\ file,\ just\ as\ in\ header\ files.\n\n'''Copyright\ notice:'''\ The\ notice\ protects\ ownership\ of\ the\ file.\ The\ copyright\ shown\ above\ is\ included\ in\ the\ Tcl\ and\ Tk\ sources.\ More\ product\ specific\ packages\ would\ probably\ have\ the\ words\ ''All\ rights\ reserved''\ included\ instead.\ If\ more\ than\ one\ entity\ contributed\ to\ the\ page\ they\ should\ each\ have\ a\ distinct\ copyright\ line.\n\n'''Revision\ string:'''\ The\ contents\ of\ this\ string\ are\ managed\ automatically\ by\ the\ source\ code\ control\ system\ for\ the\ file,\ such\ as\ RCS\ or\ SCCS\ (SCCS\ is\ used\ in\ the\ example\ in\ the\ figure).\ It\ identifies\ the\ file's\ current\ revision,\ date\ of\ last\ modification,\ and\ so\ on.\n\n'''Package\ definition:'''\ Also\ any\ require\ statements\ for\ other\ packages\ that\ this\ package\ depends\ on\ should\ be\ the\ first\ code\ in\ the\ file.\ Any\ global\ variables\ that\ are\ managed\ by\ this\ file\ should\ be\ declared\ at\ the\ top\ of\ the\ page.\ The\ name\ space\ definition\ should\ be\ next\ and\ the\ export\ list\ should\ be\ the\ first\ item\ in\ the\ namespace\ definition.\ Please\ structure\ your\ header\ pages\ in\ exactly\ the\ order\ given\ above\ and\ follow\ the\ syntax\ of\ Figure\ 1\ as\ closely\ as\ possible.\ The\ file\ fileHead.tcl\ provides\ a\ template\ for\ a\ header\npage.\n\n'''SECTION\ 4.2'''\n\n''Multi-file\ packages''\n\nSome\ packages\ may\ be\ too\ large\ to\ fit\ into\ one\ file.\ You\ may\ want\ to\ consider\ breaking\ the\ package\ into\ multiple\ independent\ packages.\ However,\ when\ that\ is\ not\ an\ option\ you\ need\ to\ make\ one\ of\ the\ files\ the\ ''primary''\ file.\ The\ primary\ file\ will\ include\ the\ complete\ export\ list\ and\ the\ definitions\ of\ all\ exported\ variables\ and\ procedures.\ The\ secondary\ files\ should\ only\ contain\ supporting\ routines\ to\ the\ primary\ file.\ It\ is\ important\ to\ construct\ your\ package\ in\ this\ manner\ or\ utilities\ like\ pkg_mkIndex\ will\ not\ work\ correctly.\ Finally,\ the\ header\ to\ the\ various\ files\ should\ make\ it\ clear\ which\ file\ is\ the\ primary\ file\ and\ which\ are\ supporting\ files.\n\n'''SECTION\ 4.3'''\n\n''Procedure\ headers''\n\nAfter\ the\ header\ you\ will\ have\ one\ or\ more\ procedures.\ Each\ procedure\ will\ begin\ with\ a\ ''procedure\ header''\ that\ gives\ overall\ documentation\ for\ the\ procedure,\ followed\ by\ the\ declaration\ and\ body\ for\ the\ procedure.\ See\ Figure\ Figure\ 2\ for\ an\ example.\ The\ header\ should\ contain\ everything\ that\ a\ caller\ of\ the\ procedure\ needs\ to\ know\ in\ order\ to\ use\ the\ procedure,\ and\ nothing\ else.\ It\ consists\ of\ three\ parts:\n\n'''Abstract:'''\ The\ first\ lines\ in\ the\ header\ give\ the\ procedure's\ name,\ followed\ by\ a\ brief\ description\ of\ what\ the\ procedure\ does.\ This\ should\ not\ be\ a\ detailed\ description\ of\ how\ the\ procedure\ is\ implemented,\ but\ rather\ a\ high-level\ summary\ of\ its\ overall\ function.\ In\ some\ cases,\ such\ as\ callback\ procedures,\ I\ recommend\ also\ describing\ the\ conditions\ under\ which\ the\ procedure\ is\ invoked\ and\ who\ calls\ the\ procedure.\n\n'''Arguments:'''\ This\ portion\ of\ the\ header\ describes\ the\ arguments\ that\ the\ procedure\ expects.\ Each\ argument\ should\ get\ at\ least\ one\ line.\ The\ comment\ should\ describe\ the\ expected\ type\ and\ describe\ it's\ function.\ Optional\ arguments\ should\ be\ pointed\ out\ and\ the\ default\ behavior\ of\ an\ unspecified\ argument\ should\ be\ mentioned.\ Comments\ for\ all\ of\ the\ arguments\ should\ line\ up\ on\ the\ same\ tab\ stop.\n\n\ #\ tcl::HistRedo\ --\n\ #\n\ #\ Fetch\ the\ previous\ or\ specified\ event,\ execute\ it,\ and\ then\n\ #\ replace\ the\ current\ history\ item\ with\ that\ event.\n\ #\n\ #\ Arguments:\n\ #\ event\ (optional)\ index\ of\ history\ item\ to\ redo.\ Defaults\n\ #\ to\ -1,\ which\ means\ the\ previous\ event.\n\ #\ Results:\n\ #\ The\ result\ is\ that\ of\ the\ command\ being\ redone.\ Also\ replaces\n\ #\ the\ current\ history\ list\ item\ with\ the\ one\ being\ redone.\n\ proc\ tcl::HistRedo\ \{\{event\ -1\}\}\ \{\n\ \ \ \ ...\n\ \}\n\ \nFigure\ 2.\ The\ header\ comments\ and\ declaration\ for\ a\ procedure.\n\n'''Results:'''\ The\ last\ part\ of\ the\ header\ describes\ the\ value\ returned\ by\ the\ procedure.\ The\ type\ and\ the\ intended\ use\ of\ the\ result\ should\ be\ described.\ This\ section\ should\ also\ mention\ any\ ''side\ effects''\ that\ are\ worth\ noting.\n\nThe\ file\ tclProcHead\ contains\ a\ template\ for\ a\ procedure\ header\ which\ should\ be\ used\ as\ a\ base\ for\ all\ new\ Tcl\ commands.\ Follow\ the\ syntax\ of\ Figure\ 2\ exactly\ (same\ indentation,\ double-dash\ after\ the\ procedure\ name,\ etc.).\n\n'''SECTION\ 4.4'''\n\n''Procedure\ declarations''\n\nThe\ procedure\ declaration\ should\ also\ follow\ exactly\ the\ syntax\ in\ Figure\ 2.\ Note\ that\ the\ procedure\ is\ defined\ outside\ the\ namespace\ command\ that\ defines\ the\ export\ list\ and\ namespace\ globals.\ The\ first\ line\ gives\ the\ proc\ keyword,\ the\ procedure\ name,\ and\ an\ argument\ list.\ If\ there\ are\ many\ arguments,\ they\ may\ spill\ onto\ additional\ lines\ (see\ Sections\ 6.1\ and\ 6.3\ for\ information\ about\ indentation).\n\n'''SECTION\ 4.5'''\n\n''Parameter\ order''\n\nProcedure\ parameters\ may\ be\ divided\ into\ three\ categories.\ In\ parameters\ only\ pass\ information\ into\ the\ procedure\ (either\ directly\ or\ by\ pointing\ to\ information\ that\ the\ procedure\ reads).\ Out\ parameters\ point\ to\ things\ in\ the\ caller's\ memory\ that\ the\ procedure\ modifies\ such\ as\ the\ name\ of\ a\ variable\ the\ procedure\ will\ modify.\ ''In-out''\ parameters\ do\ both.\ Below\ is\ a\ set\ of\ rules\ for\ deciding\ on\ the\ order\ of\ parameters\ to\ a\ procedure:\n\n1.\ Parameters\ should\ normally\ appear\ in\ the\ order\ in,\ in/out,\ out,\ except\ where\ overridden\ by\ the\ rules\ below.\n\n2.\ If\ an\ argument\ is\ actually\ a\ sub-command\ for\ the\ command\ than\ it\ should\ be\ the\ first\ argument\ of\ the\ command.\ \n\nFor\ example:\n\n\ proc\ graph::tree\ \{subCmd\ args\}\ \{\n\ \ \ \ \ switch\ \$subCmd\ \{\n\ \ \ \ \ \ \ \ \ add\ \{\n\ \ \ \ \ \ \ \ \ \ \ \ \ eval\ add_node\ \$args\n\ \ \ \ \ \ \ \ \ \}\n\ \ \ \ \ \ \ \ \ draw\ \{...\n\n3.\ If\ there\ is\ a\ group\ of\ procedures,\ all\ of\ which\ operate\ on\ an\ argument\ of\ a\ particular\ type,\nsuch\ as\ a\ file\ path\ or\ widget\ path,\ the\ argument\ should\ be\ the\ first\ argument\ to\ each\ of\ the\nprocedures\ (or\ after\ the\ sub-command\ argument).\n\n'''SECTION\ 4.6'''\n\n''Procedure\ bodies''\n\nThe\ body\ of\ a\ procedure\ follows\ the\ declaration.\ See\ Section\ 6\ for\ the\ coding\ conventions\ that\ govern\ procedure\ bodies.\ The\ curly\ braces\ enclosing\ the\ body\ should\ be\ on\ different\ lines,\ as\ shown\ in\ Figure\ Figure\ 2,\ even\ if\ the\ body\ of\ the\ procedure\ is\ empty.\n\n'''SECTION\ 5'''\ \n\n''Naming\ conventions''\n\nChoosing\ names\ is\ one\ of\ the\ most\ important\ aspects\ of\ programming.\ Good\ names\ clarify\ the\ function\ of\ a\ program\ and\ reduce\ the\ need\ for\ other\ documentation.\ Poor\ names\ result\ in\ ambiguity,\ confusion,\ and\ error.\ This\ section\ gives\ some\ general\ principles\ to\ follow\ when\ choosing\ names\ and\ lists\ specific\ rules\ for\ name\ syntax,\ such\ as\ capitalization.\n\n'''SECTION\ 5.1'''\n\n''General\ considerations''\n\nThe\ ideal\ variable\ name\ is\ one\ that\ instantly\ conveys\ as\ much\ information\ as\ possible\ about\ the\ purpose\ of\ the\ variable\ it\ refers\ to.\ When\ choosing\ names,\ play\ devil's\ advocate\ with\ yourself\ to\ see\ if\ there\ are\ ways\ that\ a\ name\ might\ be\ misinterpreted\ or\ confused.\ Here\ are\ some\ things\ to\ consider:\n\n1.\ Are\ you\ consistent?\ Use\ the\ same\ name\ to\ refer\ to\ the\ same\ thing\ everywhere.\ For\ example,\ within\ the\ code\ for\ handling\ standard\ bindings\ in\ Tk\ widgets,\ a\ standard\ name\ w\ is\ always\ used\ to\ refer\ to\ the\ window\ associated\ with\ the\ current\ event.\n\n2.\ If\ someone\ sees\ the\ name\ out\ of\ context,\ will\ they\ realize\ what\ it\ stands\ for,\ or\ could\ they\ confuse\ it\ with\ something\ else?\ For\ example,\ the\ procedure\ name\ buildStructure\ could\ get\ confused\ with\ some\ other\ part\ of\ the\ system.\ A\ name\ like\ buildGraphNode\nboth\ describes\ what\ part\ of\ the\ system\ it\ belongs\ to\ and\ what\ it\ is\ probably\ used\ for.\ \n\n3.\ Could\ this\ name\ be\ confused\ with\ some\ other\ name?\ For\ example,\ it's\ probably\ a\ mistake\ to\ have\ two\ variables\ str\ and\ string\ in\ the\ same\ procedure:\ it\ will\ be\ hard\ for\ anyone\ to\ remember\ which\ is\ which.\ Instead,\ change\ the\ names\ to\ reflect\ their\ functions.\ For\ example,\ if\ the\ strings\ are\ used\ as\ source\ and\ destination\ for\ a\ copy\ operation,\ name\ them\ src\ and\ dst.\n\n4.\ Is\ the\ name\ so\ generic\ that\ it\ doesn't\ convey\ any\ information?\ The\ variable\ str\ from\ the\ previous\ paragraph\ is\ an\ example\ of\ this\;\ changing\ its\ name\ to\ src\ makes\ the\ name\ less\ generic\ and\ hence\ conveys\ more\ information.\n\n'''SECTION\ 5.2'''\n\n''Basic\ syntax\ rules''\n\nBelow\ are\ some\ specific\ rules\ governing\ the\ syntax\ of\ names.\ Please\ follow\ the\ rules\ exactly,\ since\ they\ make\ it\ possible\ to\ determine\ certain\ properties\ of\ a\ variable\ just\ from\ its\ name.\ \n\n1.\ Exported\ names\ for\ both\ procedures\ and\ variables\ always\ start\ with\ a\ ''lower-case''\ letter.\ Procedures\ and\ variables\ that\ are\ meant\ only\ for\ use\ with\ in\ the\ current\ package\ or\ namespace\ should\ start\ with\ an\ ''upper-case''\ letter.\ We\ chose\ lower-case\ for\ the\ exported\ symbols\ because\ it\ is\ possible\ they\ may\ be\ commonly\ used\ from\ the\ command\ line\ and\ they\ should\ be\ easy\ to\ write.\ \n\nFor\ example:\n\n\ #\ CountNum\ is\ a\ private\ variable\n\ set\ CountNum\ 0\n\ #\ The\ function\ addWindow\ is\ public\n\ proc\ addWindow\ \{\}\ \{...\n\ #\ newWindow\ is\ a\ public\ interface\ in\ the\ spectcl\ namespace\n\ proc\ spectcl::newWindow\ \{\}\ \{...\n\ \n2.\ In\ multi-word\ names,\ the\ first\ letter\ of\ each\ trailing\ word\ is\ capitalized.\ Do\ not\ use\ underscores\ or\ dashes\ as\ separators\ between\ the\ words\ of\ a\ name.\n\n\ set\ numWindows\ 0\n\n3.\ Any\ variable\ whose\ value\ refers\ to\ another\ variable\ has\ a\ name\ that\ ends\ in\ Name.\ Furthermore,\ the\ name\ should\ also\ indicate\ what\ type\ of\ variable\ the\ name\ is\ referring\ to.\ These\ names\ are\ often\ used\ in\ arguments\ to\ procedures\ that\ are\ taking\ a\ name\ of\ a\ variable.\n\n\ proc\ foo::Bar\ \{arrayName\}\ \{\n\ \ \ \ upvar\ 1\ \$arrayName\ array\n\ \ \ \ ...\n\ \}\n\n4.\ Variables\ that\ hold\ Tcl\ code\ that\ will\ be\ evaled\ should\ have\ names\ ending\ in\ Script.\n\n\ proc\ log::eval\ \{logScript\}\ \{\n\ \ \ \ \ if\ \{\$Log::logOn\}\ \{\n\ \ \ \ \ \ \ \ \ set\ result\ \[catch\ \{eval\ \$logScript\}\ msg\]\n\ \ \ \ \ \ \ \ \ ...\n\n5.\ Variables\ that\ hold\ a\ partial\ Tcl\ command\ that\ must\ have\ additional\ arguments\ appended\ before\ being\ a\ valid\ script\ should\ have\ names\ ending\ in\ Cmd.\n\n\ foreach\ scrollCmd\ \$listScrollCmds\ \{\n\ \ \ \ \ eval\ \$scrollCmd\ \$args\n\ \}\n\n'''SECTION\ 6'''\n\n''Low-level\ coding\ conventions''\n\nThis\ section\ describes\ several\ low-level\ syntactic\ rules\ for\ writing\ Tcl\ code.\ These\ rules\ help\ to\ ensure\ that\ all\ of\ the\ Tcl\ code\ looks\ the\ same,\ and\ they\ prohibit\ a\ few\ confusing\ coding\ constructs.\n\n'''SECTION\ 6.1'''\n\n''Indents\ are\ 4\ spaces''\n\nEach\ level\ of\ indentation\ should\ be\ four\ spaces.\ There\ are\ ways\ to\ set\ 4-space\ indents\ in\ all\ of\ the\ most\ common\ editors.\ Be\ sure\ that\ your\ editor\ really\ uses\ four\ spaces\ for\ the\ indent,\ rather\ than\ just\ displaying\ tabs\ as\ four\ spaces\ wide\;\ if\ you\ use\ the\ latter\ approach\ then\ the\ indents\ will\ appear\ eight\ spaces\ wide\ in\ other\ editors.\n\n'''SECTION\ 6.2'''\n\n''Code\ comments\ occupy\ full\ lines''\n\nComments\ that\ document\ code\ should\ occupy\ full\ lines,\ rather\ than\ being\ tacked\ onto\ the\ ends\ of\ lines\ containing\ code.\ The\ reason\ for\ this\ is\ that\ side-by-side\ comments\ are\ hard\ to\ see,\ particularly\ if\ neighboring\ statements\ are\ long\ enough\ to\ overlap\ the\ \ side-by-side\ comments.\ Also\ it\ is\ easy\ to\ place\ comments\ in\ a\ place\ that\ could\ cause\ errors.\ Comments\ must\ have\ exactly\nthe\ structure\ shown\ in\ Figure\ 3,\ with\ a\ blank\ line\ above\ and\ below\ the\ comment.\ The\ leading\ blank\ line\ can\ be\ omitted\ if\ the\ comment\ is\ at\ the\ beginning\ of\ a\ block,\ as\ is\ the\ case\ in\ the\ second\ comment\ in\ Figure\ 3.\ Each\ comment\ should\ be\ indented\ to\ the\ same\ level\ as\ the\ surrounding\ code.\ Use\ proper\ English\ in\ comments:\ write\ complete\ sentences,\ capitalize\ the\ first\ word\ of\ each\ sentence,\ and\ so\non.\n\n\ #\ If\ we\ are\ running\ on\ the\ Macintosh\ platform\ then\ we\ can\n\ #\ assume\ that\ the\ sources\ are\ located\ in\ the\ resource\ fork\n\ #\ of\ our\ application,\ and\ we\ do\ not\ need\ to\ search\ for\ them.\n\ if\ \{\$tcl_platform(platform)\ ==\ \"macintosh\"\}\ \{\n\ \ \ \ \ return\n\ \}\n\ foreach\ dir\ \$dirList\ \{\n\ \ \ \ \ #\ If\ the\ source\ succeeds\ then\ we\ are\ done.\n\ \ \ \ \ if\ \{!\[catch\ \{source\ \[file\ join\ \$dir\ file.tcl\]\}\]\}\ \{\n\ \ \ \ \ \ \ \ \ break\n\ \ \ \ \ \}\n\ \}\n\n\nFigure\ 3.\ Comments\ in\ code\ have\ the\ form\ shown\ above,\ using\ full\ lines,\ with\ lined-up\ hashmarks,\ the\ comment\ takes\ at\ least\ a\ full\ \ \ \ \ \ \ line\ and\ blank\ separator\ lines\ around\ each\ comment\ (except\ that\ the\ leading\ blank\ line\ can\ be\ omitted\ if\ the\ comment\ is\ at\ the\ beginning\ of\ a\ code\ block)\ \n\ \ \n\n'''SECTION\ 6.3'''\n\n''Continuation\ lines\ are\ indented\ 8\ spaces\ ''\n\nYou\ should\ use\ continuation\ lines\ to\ make\ sure\ that\ no\ single\ line\ exceeds\ 80\ characters\ in\ length.\ Continuation\ lines\ should\ be\ indented\ 8\ spaces\ so\ that\ they\ won't\ be\ confused\ with\ an\ immediately-following\ nested\ block.\ Pick\ clean\ places\ to\ break\ your\ lines\ for\ continuation,\ so\ that\ the\ continuation\ doesn't\ obscure\ the\ structure\ of\ the\ statement.\ For\ example,\ if\ a\ procedure\ call\ requires\ continuation\ lines,\ try\ to\ avoid\ situations\ where\ a\ single\ argument\ spans\ multiple\ lines.\ If\ the\ test\ for\ an\ if\ or\ while\ command\ spans\ lines,\ try\ to\ make\ each\ line\ have\ the\ same\ nesting\ level\ of\ parentheses\ and/or\ brackets\ if\ possible.\ I\ try\ to\ start\ each\ continuation\ line\ with\ an\ operator\ such\ as\ *,\ &&,\ or\ ||\;\ this\ makes\ it\ clear\ that\ the\ line\ is\ a\ continuation,\ \nsince\ a\ new\ statement\ would\ never\ start\ with\ such\ an\ operator.\n\n'''SECTION\ 6.4'''\n\n''Only\ one\ command\ per\ line''\n\nYou\ should\ only\ have\ one\ Tcl\ command\ per\ line\ on\ the\ page.\ Do\ not\ use\ the\ semi-colon\ character\ to\ place\ multiple\ commands\ on\ the\ same\ line.\ This\ makes\ the\ code\ easier\ to\ read\ and\ helps\ with\ debugging.\n\n'''SECTION\ 6.5'''\n\n''Curly\ braces:\ \{\ goes\ at\ the\ end\ of\ a\ line''\n\nOpen\ curly\ braces\ can\ not\ appear\ on\ lines\ by\ themselves\ in\ Tcl.\ Instead,\ they\ should\ be\ placed\ at\ the\ end\ of\ the\ preceding\ line.\ Close\ curly\ braces\ are\ indented\ to\ the\ same\ level\ as\ the\ outer\ code,\ i.e.,\ four\ spaces\ less\ than\ the\ statements\ they\ enclose.\ However,\ you\ should\ ''always''\ use\ curly\ braces\ rather\ than\ some\ other\ list\ generating\ mechanism\ that\ will\ work\ in\ the\ Tcl\ language.\ This\ will\ help\ make\ code\ more\ readable,\ will\ avoid\ unwanted\ side\ effects,\ and\ in\ many\ cases\ will\ generate\ faster\ code\ with\ the\ Tcl\ compiler.\n\nControl\ structures\ should\ always\ use\ curly\ braces,\ even\ if\ there\ is\ only\ one\ statement\ in\nthe\ block.\ Thus\ you\ shouldn't\ write\ code\ like:\n\n\ if\ \{\$tcl_platform(platform)\ ==\ \"unix\"\}\ return\n\nbut\ rather:\n\n\ if\ \{\$tcl_platform(platform)\ ==\ \"unix\"\}\ \{\n\ \ \ \ \ return\n\ \}\n\nThis\ approach\ makes\ code\ less\ dense,\ but\ it\ avoids\ potential\ mistakes\ like\ unwanted\ Tcl\ substitutions.\ It\ also\ makes\ it\ easier\ to\ set\ breakpoints\ in\ a\ debugger,\ since\ it\ guarantees\ that\ each\ statement\ is\ on\ a\ separate\ line\ and\ can\ be\ named\ individually.\n\n'''SECTION\ 6.6'''\n\n''Parenthesize\ expressions''\n\nUse\ parentheses\ around\ each\ subexpression\ in\ an\ expression\ to\ make\ it\ absolutely\ clear\ what\ is\ the\ evaluation\ order\ of\ the\ expression\ (a\ reader\ of\ your\ code\ should\ not\ need\ to\ remember\ Tcl's\ precedence\ rules).\ \n\nFor\ example,\ don't\ type:\n\ \n\ if\ \{\$x\ >\ 22\ &&\ \$y\ <=\ 47\}\ ...\n\nInstead,\ type\ this:\n\ \n\ if\ \{(\$x\ >\ 22)\ &&\ (\$y\ <=\ 47)\}\ ...\n\n'''SECTION\ 6.7'''\n\n''Always\ use\ the\ return\ statement''\n\nYou\ should\ always\ explicitly\ use\ the\ return\ statement\ to\ return\ values\ from\ a\ Tcl\ procedure.\ By\ default\ Tcl\ will\ return\ the\ value\ of\ the\ last\ Tcl\ statement\ executed\ in\ a\ Tcl\ procedure\ as\ the\ return\ value\ of\ the\ procedure\ which\ often\ leads\ to\ confusion\ as\ to\ where\ the\ result\ is\ coming\ from.\ In\ addition,\ you\ should\ use\ a\ return\ statement\ with\ no\ argument\ for\ procedures\ whose\ results\ are\ ignored.\ Supplying\ this\ return\ will\ actually\ speed\ up\ your\ application\ with\ the\ new\ Tcl\ compiler.\ \n\nFor\ example,\ don't\ write\ code\ like\ this:\n\n\ proc\ foo\ \{x\ y\}\ \{\n\ \ \ \ \ if\ \{\$x\ <\ 0\}\ \{\n\ \ \ \ \ \ \ \ \ incr\ x\n\ \ \ \ \ \}\ else\ \{\n\ \ \ \ \ \ \ \ \ expr\ \$x\ +\ \$y\n\ \ \ \ \ \}\n\ \}\n\nBut\ rather,\ type\ this:\n\n\ proc\ foo\ \{x\ y\}\ \{\n\ \ \ \ \ if\ \{\$x\ <\ 0\}\ \{\n\ \ \ \ \ \ \ \ \ return\ \[incr\ x\]\n\ \ \ \ \ \}\ else\ \{\n\ \ \ \ \ \ \ \ \ return\ \[expr\ \$x\ +\ \$y\]\n\ \ \ \ \ \}\n\ \}\n\nFor\ Tcl\ procedures\ that\ have\ no\ return\ value\ a\ single\ return\ statement\ with\ no\ arguments\ is\ placed\ at\ the\ end\ of\ the\ procedure.\n\n'''SECTION\ 6.8'''\n\n''Switch\ statements''\n\nThe\ switch\ statement\ should\ be\ formatted\ as\ below.\ Always\ use\ the\ --\ option\ to\ avoid\ having\ the\ string\ be\ confused\ with\ an\ option.\ This\ can\ happen\ when\ the\ string\ is\ user\ generated.\ Comments\ can\ be\ added\ on\ the\ same\ line\ as\ the\ pattern\ to\ comment\ the\ pattern\ case.\ The\ comments\ for\ each\ case\ should\ line\ up\ on\ the\ same\ tab\ stop\ and\ must\ be\ within\ the\ braces.\ Note\ that\ this\ is\ an\ exception\ to\ the\ standard\ commenting\ conventions.\n\n\ switch\ -regexp\ --\ \$string\ \{\n\ \ \ \ \ plus\ -\n\ \ \ \ \ add\ \{\ \ \ \ \ \ \ \ #\ Do\ add\ task\n\ \ \ \ \ \ \ \ \ ...\n\ \ \ \ \ \}\n\ \ \ \ \ subtract\ \{\ \ \ #\ Do\ subtract\ case\n\ \ \ \ \ \ \ \ \ ...\n\ \ \ \ \ \}\n\ \ \ \ \ default\ \{\n\ \ \ \ \ \ \ \ \ ...\n\ \ \ \ \ \}\n\ \}\n\n'''SECTION\ 6.9'''\n\n''If\ statements''\n\nNever\ use\ the\ '''''then'''''\ word\ of\ an\ '''''if'''''\ statement.\ It\ is\ syntactic\ sugar\ that\ really\ isn't\ that\ useful.\ However,\ the\ else\ word\ should\ always\ be\ used\ as\ it\ does\ impart\ some\ semantic\ information\ and\ it\ is\ more\ like\ the\ C\ language.\ \n\nHere\ is\ an\ example:\n\ \n\ if\ \{\$x\ <\ 0\}\ \{\n\ \ \ \ \ ...\n\ \}\ elseif\ \{\$x\ ==\ 0\}\ \{\n\ \ \ \ \ ...\n\ \}\ else\ \{\n\ \ \ \ \ ...\n\ \}\n\n'''SECTION\ 7'''\n\n''Documenting\ code''\n\nThe\ purpose\ of\ documentation\ is\ to\ save\ time\ and\ reduce\ errors.\ Documentation\ is\ typically\ used\ for\ two\ purposes.\ First,\ people\ will\ read\ the\ documentation\ to\ find\ out\ how\ to\ use\ your\ code.\ For\ example,\ they\ will\ read\ procedure\ headers\ to\ learn\ how\ to\ call\ the\ procedures.\ Ideally,\ people\ should\ have\ to\ learn\ as\ little\ as\ possible\ about\ your\ code\ in\ order\ to\ use\ it\ correctly.\ Second,\ people\ will\ read\ the\ documentation\ to\ find\ out\ how\ your\ code\ works\ internally,\ so\ they\ can\ fix\ bugs\ or\ add\ new\ features\;\ again,\ good\ documentation\ will\ allow\ them\ to\ make\ their\ fixes\ or\ enhancements\ while\ learning\ the\ minimum\ possible\ about\ your\ code.\ More\ documentation\ isn't\ necessarily\ better:\ wading\ through\ pages\ of\ documentation\ may\ not\ be\ any\ easier\ than\ deciphering\ the\ code.\ Try\ to\ pick\ out\ the\ most\ important\ things\ that\ will\ help\ people\ to\ understand\ your\ code\ and\ focus\ on\ these\ in\ your\ documentation.\n\n'''SECTION\ 7.1'''\n\n''Document\ things\ with\ wide\ impact''\n\nThe\ most\ important\ things\ to\ document\ are\ those\ that\ affect\ many\ different\ pieces\ of\ a\ program.\ Thus\ it\ is\ essential\ that\ every\ procedure\ interface,\ every\ structure\ declaration,\ and\ every\ global\ variable\ be\ documented\ clearly.\ If\ you\ haven't\ documented\ one\ of\ these\ things\ it\ will\ be\ necessary\ to\ look\ at\ all\ the\ uses\ of\ the\ thing\ to\ figure\ out\ how\ it's\ supposed\ to\ work\;\ this\ will\ be\ntime-consuming\ and\ error-prone.\n\nOn\ the\ other\ hand,\ things\ with\ only\ local\ impact\ may\ not\ need\ much\ documentation.\ For\ example,\ in\ short\ procedures\ I\ don't\ usually\ have\ comments\ explaining\ the\ local\ variables.\ If\ the\ overall\ function\ of\ the\ procedure\ has\ been\ explained,\ and\ if\ there\ isn't\ much\ code\ in\ the\ procedure,\ and\ if\ the\ variables\ have\ meaningful\ names,\ then\ it\ will\ be\ easy\ to\ figure\ out\ how\ they\ are\ used.\ On\ the\ other\ hand,\ for\ long\ procedures\ with\ many\ variables\ I\ usually\ document\ the\ key\ variables.\ Similarly,\ when\ I\ write\ short\ procedures\ I\ don't\ usually\ have\ any\ comments\ in\ the\ procedure's\ code:\ the\ procedure\ header\ provides\ enough\ information\ to\ figure\ out\ what\ is\ going\ on.\ For\ long\ procedures\ I\ place\ a\ comment\ block\ before\ each\ major\ piece\ of\ the\ procedure\ to\ clarify\ the\ overall\ flow\ through\ the\ procedure.\n\n'''SECTION\ 7.2'''\n\n''Don't\ just\ repeat\ what's\ in\ the\ code''\n\nThe\ most\ common\ mistake\ I\ see\ in\ documentation\ (besides\ it\ not\ being\ there\ at\ all)\ is\ that\ it\ repeats\ what\ is\ already\ obvious\ from\ the\ code,\ such\ as\ this\ trivial\ (but\ exasperatingly\ common).\n\nexample:\n\n\ #\ Increment\ i.\n\ incr\ i\n\nDocumentation\ should\ provide\ higher-level\ information\ about\ the\ overall\ function\ of\ the\ code,\ helping\ readers\ to\ understand\ what\ a\ complex\ collection\ of\ statements\ really\ means.\ For\ example,\ the\ comment\n\n\ #\ Probe\ into\ the\ array\ to\ see\ if\ the\ symbol\ exists.\n\nis\ likely\ to\ be\ much\ more\ helpful\ than\ \n\n\ #\ Loop\ through\ every\ array\ index,\ get\ the\ third\ value\ of\ the\n\ #\ list\ in\ the\ content\ to\ determine\ if\ it\ has\ the\ symbol\ we\ are\n\ #\ looking\ for.\ Set\ the\ result\ to\ the\ symbol\ if\ we\ find\ it.\n\ \nEverything\ in\ this\ second\ comment\ is\ probably\ obvious\ from\ the\ code\ that\ follows\ it.\ Another\ thing\ to\ consider\ in\ your\ comments\ is\ word\ choice.\ Use\ different\ words\ in\ the\ comments\ than\ the\ words\ that\ appear\ in\ variable\ or\ procedure\ names.\ For\ example,\ the\ comment\n\n\ #\ SwapPanels\ --\n\ #\n\ #\ \ \ \ Swap\ the\ panels.\n\ #\ ...\n\nis\ not\ a\ very\ useful\ comment.\ Everything\ in\ the\ comment\ is\ already\ obvious\ from\ the\ procedure's\ name.\ Here\ is\ a\ much\ more\ useful\ comment:\n\n\ #\ SwapPanels\ --\n\ #\n\ #\ \ \ Unmap\ the\ current\ UI\ panel\ from\ the\ parent\ frame\ and\ replace\n\ #\ \ \ it\ with\ the\ newly\ specified\ frame.\ Make\ sure\ that\ the\ new\n\ #\ \ \ panel\ fits\ into\ the\ old\ frame\ and\ resize\ if\ needed.\n\ #\ ...\n\ \nThis\ comment\ tells\ why\ you\ might\ want\ to\ use\ the\ procedure,\ in\ addition\ to\ what\ it\ does,\ which\ makes\ the\ comment\ much\ more\ useful.\n\n'''SECTION\ 7.3'''\n\n''Document\ each\ thing\ in\ exactly\ one\ place''\n\nSystems\ evolve\ over\ time.\ If\ something\ is\ documented\ in\ several\ places,\ it\ will\ be\ hard\ to\ keep\ the\ documentation\ up\ to\ date\ as\ the\ system\ changes.\ Instead,\ try\ to\ document\ each\ major\ design\ decision\ in\ exactly\ one\ place,\ as\ near\ as\ possible\ to\ the\ code\ that\ implements\ the\ design\ decision.\ The\ principal\ documentation\ for\ each\ procedure\ goes\ in\ the\ procedure\ header.\ There's\ no\ need\ to\ repeat\ this\ information\ again\ in\ the\ body\ of\ the\ procedure\ (but\ you\ might\ have\ additional\ comments\ in\ the\ procedure\ body\ to\ fill\ in\ details\ not\ described\ in\ the\ procedure\ header).\ If\ a\ library\ procedure\ is\ documented\ thoroughly\ in\ a\ manual\ entry,\ then\ I\ may\ make\nthe\ header\ for\ the\ procedure\ very\ terse,\ simply\ referring\ to\ the\ manual\ entry.\ \n\nThe\ other\ side\ of\ this\ coin\ is\ that\ every\ major\ design\ decision\ needs\ to\ be\ documented\ at\ least\ once.\ If\ a\ design\ decision\ is\ used\ in\ many\ places,\ it\ may\ be\ hard\ to\ pick\ a\ central\ place\ to\ document\ it.\ Try\ to\ find\ a\ data\ structure\ or\ key\ procedure\ where\ you\ can\ place\ the\ main\ body\ of\ comments\;\ then\ reference\ this\ body\ in\ the\ other\ places\ where\ the\ decision\ is\ used.\ If\ all\ else\ fails,\ add\ a\ block\ of\ comments\ to\ the\ header\ page\ of\ one\ of\ the\ files\ implementing\ the\ decision.\n\n'''SECTION\ 7.4'''\n\n''Write\ clean\ code''\n\nThe\ best\ way\ to\ produce\ a\ well-documented\ system\ is\ to\ write\ clean\ and\ simple\ code.\ This\ way\ there\ won't\ be\ much\ to\ document.\ If\ code\ is\ clean,\ it\ means\ that\ there\ are\ a\ few\ simple\ ideas\ that\ explain\ its\ operation\;\ all\ you\ have\ to\ do\ is\ to\ document\ those\ key\ ideas.\ When\ writing\ code,\ ask\ yourself\ if\ there\ is\ a\ simple\ concept\ behind\ the\ code.\ If\ not,\ perhaps\ you\ should\ rethink\ the\ code.\ If\ it\ takes\ a\ lot\ of\ documentation\ to\ explain\ a\ piece\ of\ code,\ it\ is\ a\ sign\ that\ you\ haven't\ found\ a\ clean\ solution\ to\ the\ problem.\n\n'''SECTION\ 7.5'''\n\n''Document\ as\ you\ go''\n\nIt\ is\ extremely\ important\ to\ write\ the\ documentation\ as\ you\ write\ the\ code.\ It's\ very\ tempting\ to\ put\ off\ the\ documentation\ until\ the\ end\;\ after\ all,\ the\ code\ will\ change,\ so\ why\ waste\ time\ writing\ documentation\ now\ when\ you'll\ have\ to\ change\ it\ later?\ The\ problem\ is\ that\ the\ end\ never\ comes\ —\ there\ is\ always\ more\ code\ to\ write.\ Also,\ the\ more\ undocumented\ code\ that\ you\ accumulate,\ the\ harder\ it\ is\ to\ work\ up\ the\ energy\ to\ document\ it.\ So,\ you\ just\ write\ more\ undocumented\ code.\ I've\ seen\ many\ people\ start\ a\ project\ fully\ intending\ to\ go\ back\ at\ the\ end\ and\ write\ all\ the\ documentation,\ but\ I've\ never\ seen\ anyone\ actually\ do\ it.\n\nIf\ you\ do\ the\ documentation\ as\ you\ go,\ it\ won't\ add\ much\ to\ your\ coding\ time\ and\ you\ won't\ have\ to\ worry\ about\ doing\ it\ later.\ Also,\ the\ best\ time\ to\ document\ code\ is\ when\ the\ key\ ideas\ are\ fresh\ in\ your\ mind,\ which\ is\ when\ you're\ first\ writing\ the\ code.\ When\ I\ write\ new\ code,\ I\ write\ all\ of\ the\ header\ comments\ for\ a\ group\ of\ procedures\ before\ I\ fill\ in\ any\ of\ the\ bodies\ of\ the\ procedures.\ This\ way\ I\ can\ think\ about\ the\ overall\ structure\ and\ how\ the\ pieces\ fit\ together\ before\ getting\ bogged\ down\ in\ the\ details\ of\ individual\ procedures.\n\n'''SECTION\ 7.6'''\n\n''Document\ tricky\ situations''\n\nIf\ code\ is\ non-obvious,\ meaning\ that\ its\ structure\ and\ correctness\ depend\ on\ information\ that\ won't\ be\ obvious\ to\ someone\ reading\ it\ for\ the\ first\ time,\ be\ sure\ to\ document\ the\ non-obvious\ information.\ One\ good\ indicator\ of\ a\ tricky\ situation\ is\ a\ bug.\ If\ you\ discover\ a\ subtle\ property\ of\ your\ program\ while\ fixing\ a\ bug,\ be\ sure\ to\ add\ a\ comment\ explaining\ the\ problem\ and\ its\nsolution.\ Of\ course,\ it's\ even\ better\ if\ you\ can\ fix\ the\ bug\ in\ a\ way\ that\ eliminates\ the\ subtle\ behavior,\ but\ this\ isn't\ always\ possible.\n\n'''SECTION\ 8'''\n\n''Testing''\n\nOne\ of\ the\ environments\ where\ Tcl\ works\ best\ is\ for\ testing.\ While\ Tcl\ has\ traditionally\ been\ used\ for\ testing\ C\ code\ it\ is\ equally\ as\ good\ at\ testing\ other\ Tcl\ code.\ Whenever\ you\ write\ new\ code\ you\ should\ write\ Tcl\ test\ scripts\ to\ go\ with\ that\ code\ and\ save\ the\ tests\ in\ files\ so\ that\ they\ can\ be\ re-run\ later.\ Writing\ test\ scripts\ isn't\ as\ tedious\ as\ it\ may\ sound.\ If\ you're\ developing\nyour\ code\ carefully\ you're\ already\ doing\ a\ lot\ of\ testing\;\ all\ you\ need\ to\ do\ is\ type\ your\ test\ cases\ into\ a\ script\ file\ where\ they\ can\ be\ reused,\ rather\ than\ typing\ them\ interactively\ where\ they\ vanish\ after\ they're\ run.\n\n'''SECTION\ 8.1'''\n\n''Basics''\n\nTests\ should\ be\ organized\ into\ script\ files,\ where\ each\ file\ contains\ a\ collection\ of\ related\ tests.\ Individual\ tests\ should\ be\ based\ on\ the\ procedure\ test,\ just\ like\ in\ the\ Tcl\ and\ Tk\ test\ suites.\ Here\ are\ two\ examples:\n\n\ test\ expr-3.1\ \{floating-point\ operators\}\ \{\n\ \ \ \ \ expr\ 2.3*.6\n\ \}\ 1.38\n\n\ test\ expr-3.2\ \{floating-point\ operators\}\ \{unixOnly\}\ \{\n\ \ \ \ \ list\ \[catch\ \{expr\ 2.3/0\}\ msg\]\ \$msg\n\ \}\ \{1\ \{divide\ by\ zero\}\}\n\n''test''\ is\ a\ procedure\ defined\ in\ a\ script\ file\ named\ defs,\ which\ is\ sourced\ by\ each\ test\ file.\ ''test''\ takes\ four\ or\ five\ arguments:\ a\ test\ identifier,\ a\ string\ describing\ the\ test,\ an\ optional\ argument\ describing\ the\ conditions\ under\ which\ this\ test\ should\ run,\ a\ test\ script,\ and\ the\ expected\ result\ of\ the\ script.\ test\ evaluates\ the\ script\ and\ checks\ to\ be\ sure\ that\ it\ produces\nthe\ expected\ result.\ If\ not,\ it\ prints\ a\ message\ like\ the\ following:\n\n\ ====\ expr-3.1\ floating-point\ operators\n\ ====\ Contents\ of\ test\ case:\n\ \ \ \ \ expr\ 2.3*.6\n\ ====\ Result\ was:\n\ 1.39\n\ ----\ Result\ should\ have\ been:\n\ 1.38\n\ ----\ expr-3.1\ FAILED\n\nTo\ run\ a\ set\ of\ tests,\ you\ start\ up\ the\ application\ and\ source\ a\ test\ file.\ If\ all\ goes\ well\ no\ messages\ appear\;\ if\ errors\ are\ detected,\ a\ message\ is\ printed\ for\ each\ error.\ \n\nThe\ test\ identifier,\ such\ as\ expr-3.1,\ is\ printed\ when\ errors\ occur.\ It\ can\ be\ used\ to\ search\ a\ test\ script\ to\ locate\ the\ source\ for\ a\ failed\ test.\ The\ first\ part\ of\ the\ identifier,\ such\ as\ expr,\ should\ be\ the\ same\ as\ the\ name\ of\ the\ test\ file,\ except\ that\ the\ test\ file\ should\ have\ a\ .test\ extension,\ such\ as\ expr.test.\ The\ two\ numbers\ allow\ you\ to\ divide\ your\ tests\ into\ groups.\ The\ tests\ in\ a\ particular\ group\ (e.g.,\ all\ the\ expr-3.n\ tests)\ relate\ to\ a\ single\ sub-feature,\ such\ as\ a\ single\ procedure.\ The\ tests\ should\ appear\ in\ the\ test\ file\ in\ the\ same\ order\ as\ their\ numbers.\n\nThe\ test\ name,\ such\ as\ ''floating-point\ operators'',\ is\ printed\ when\ errors\ occur.\ It\ provides\ human-readable\ information\ about\ the\ general\ nature\ of\ the\ test.\n\nBefore\ writing\ tests\ I\ suggest\ that\ you\ look\ over\ some\ of\ the\ test\ files\ for\ Tcl\ and\ Tk\ to\ see\ how\ they\ are\ structured.\ You\ may\ also\ want\ to\ look\ at\ the\ README\ files\ in\ the\ Tcl\ and\ Tk\ test\ directories\ to\ learn\ about\ additional\ features\ that\ provide\ more\ verbose\ output\ or\ restrict\ the\ set\ of\ tests\ that\ are\ run.\n\n'''SECTION\ 8.2'''\n\n''Organizing\ tests''\n\nOrganize\ your\ tests\ to\ match\ the\ code\ being\ tested.\ The\ best\ way\ to\ do\ this\ is\ to\ have\ one\ test\ file\ for\ each\ source\ code\ file,\ with\ the\ name\ of\ the\ test\ file\ derived\ from\ the\ name\ of\ the\ source\ file\ in\ an\ obvious\ way\ (e.g.\ http.test\ contains\ tests\ for\ the\ code\ in\ http.tcl).\ Within\ the\ test\ file,\ have\ one\ group\ of\ tests\ for\ each\ procedure\ (for\ example,\ all\ the\ http-3.n\ tests\ in\ http.test\ are\ for\ the\ procedure\ http::geturl).\ The\ order\ of\ the\ tests\ within\ a\ group\ should\ be\ the\ same\ as\ the\ order\ of\ the\ code\ within\ the\ procedure.\ This\ approach\ makes\ it\ easy\ to\ find\ the\ tests\ for\ a\ particular\ piece\ of\ code\ and\ add\ new\ tests\ as\ the\ code\ changes.\ The\ Tcl\ test\ suite\ was\ written\ a\ long\ time\ ago\ and\ uses\ a\ different\ style\ where\ there\ is\ one\ file\ for\ each\ Tcl\ command\ or\ group\ of\ related\ commands,\ and\ the\ tests\ are\ grouped\ within\ the\ file\ by\ sub-command\ or\ features.\ In\ this\ approach\ the\ relationship\ between\ tests\ and\ particular\ pieces\ of\ code\ is\ much\ less\ obvious,\ so\ it\ is\ harder\ to\ maintain\ the\ tests\ as\ the\ code\nevolves.\ I\ don't\ recommend\ using\ this\ approach\ for\ new\ tests.\n\n'''SECTION\ 8.3'''\n\n''Coverage''\n\nWhen\ writing\ tests,\ you\ should\ attempt\ to\ exercise\ every\ line\ of\ source\ code\ at\ least\ once.\ There\ will\ be\ occasionally\ be\ code\ that\ you\ can't\ exercise,\ such\ as\ code\ that\ exits\ the\ application,\ but\ situations\ like\ this\ are\ rare.\ You\ may\ find\ it\ hard\ to\ exercise\ some\ pieces\ of\ code\ because\ existing\ Tcl\ commands\ don't\ provide\ fine\ enough\ control\ to\ generate\ all\ the\ possible\ execution\ paths.\ In\ situations\ like\ this,\ write\ one\ or\ more\ new\ Tcl\ commands\ just\ for\ testing\ purposes.\ It's\ much\ better\ to\ test\ a\ facility\ directly\ then\ to\ rely\ on\ some\ side\ effect\ for\ testing\ that\ may\ change\ over\ time.\ Use\ a\ similar\ approach\ in\ your\ own\ code,\ where\ you\ have\ an\ extra\nfile\ with\ additional\ commands\ for\ testing.\n\nIt's\ not\ sufficient\ just\ to\ make\ sure\ each\ line\ of\ code\ is\ executed\ by\ your\ tests.\ In\ addition,\ your\ tests\ must\ discriminate\ between\ code\ that\ executes\ correctly\ and\ code\ that\ isn't\ correct.\ For\ example,\ write\ tests\ to\ make\ sure\ that\ the\ then\ and\ else\ branches\ of\ each\ if\ statement\ are\ taken\ under\ the\ correct\ conditions.\ For\ a\ loop,\ run\ different\ tests\ to\ make\ the\ loop\ execute\ zero\ times,\ one\ time,\ and\ two\ or\ more\ times.\ If\ a\ piece\ of\ code\ removes\ an\ element\ from\ a\ list,\ try\ cases\ where\ the\ element\ to\ be\ removed\ is\ the\ first\ element,\ last\ element,\ only\ element,\ and\ neither\ first\ element\ nor\ last.\ Try\ to\ find\ all\ the\ places\ where\ different\ pieces\ of\ code\ interact\ in\ unusual\ ways,\ and\ exercise\ the\ different\ possible\ interactions.\n\n'''SECTION\ 8.4'''\n\n''Fixing\ bugs''\n\nWhenever\ you\ find\ a\ bug\ in\ your\ code\ it\ means\ that\ the\ test\ suite\ wasn't\ complete.\ As\ part\ of\ fixing\ the\ bug,\ you\ should\ add\ new\ tests\ that\ detect\ the\ presence\ of\ the\ bug.\ I\ recommend\ writing\ the\ tests\ after\ you've\ located\ the\ bug\ but\ ''before''\ you\ fix\ it.\ That\ way\ you\ can\ verify\ that\ the\ bug\ happens\ before\ you\ implement\ the\ fix\ and\ the\ bug\ doesn't\ happen\ afterwards,\ so\ you'll\ know\ you've\ really\ fixed\ something.\ Use\ bugs\ to\ refine\ your\ testing\ approach:\ think\ about\ what\ you\ might\ be\ able\ to\ do\ differently\ when\ you\ write\ tests\ in\ the\ future\ to\ keep\ bugs\ like\ this\ one\ from\ going\ undetected.\n\n'''SECTION\ 8.5'''\n\n''Tricky\ features''\n\nI\ also\ use\ tests\ as\ a\ way\ of\ illustrating\ the\ need\ for\ tricky\ code.\ If\ a\ piece\ of\ code\ has\ an\ unusual\ structure,\ and\ particularly\ if\ the\ code\ is\ hard\ to\ explain,\ I\ try\ to\ write\ additional\ tests\ that\ will\ fail\ if\ the\ code\ is\ implemented\ in\ the\ obvious\ manner\ instead\ of\ using\ the\ tricky\ approach.\ This\ way,\ if\ someone\ comes\ along\ later,\ doesn't\ understand\ the\ documentation\ for\ the\ code,\ decides\ the\ complex\ structure\ is\ unnecessary,\ and\ changes\ the\ code\ back\ to\ the\ simple\ (but\ incorrect)\ form,\ the\ test\ will\ fail\ and\ the\ person\ will\ be\ able\ to\ use\ the\ test\ to\ understand\ why\ the\ code\ needs\ to\ be\ the\ way\ it\ is.\ Illustrative\ tests\ are\ not\ a\ substitute\ for\ good\ndocumentation,\ but\ they\ provide\ a\ useful\ addition.\n\n'''SECTION\ 8.6'''\n\n''Test\ independence''\n\nTry\ to\ make\ tests\ independent\ of\ each\ other,\ so\ that\ each\ test\ can\ be\ understood\ in\ isolation.\ For\ example,\ one\ test\ shouldn't\ depend\ on\ commands\ executed\ in\ a\ previous\ test.\ This\ is\ important\ because\ the\ test\ suite\ allows\ tests\ to\ be\ run\ selectively:\ if\ the\ tests\ depend\ on\ each\ other,\ then\ false\ errors\ will\ be\ reported\ when\ someone\ runs\ a\ few\ of\ the\ tests\ without\ the\ others.\ \n\nFor\ convenience,\ you\ may\ execute\ a\ few\ statements\ in\ the\ test\ file\ to\ set\ up\ a\ test\ configuration\ and\ then\ run\ several\ tests\ based\ on\ that\ configuration.\ If\ you\ do\ this,\ put\ the\ setup\ code\ outside\ the\ calls\ to\ the\ test\ procedure\ so\ it\ will\ always\ run\ even\ if\ the\ individual\ tests\ aren't\ run.\ I\ suggest\ keeping\ a\ very\ simple\ structure\ consisting\ of\ setup\ followed\ by\ a\ group\ of\ tests.\ Don't\ perform\ some\ setup,\ run\ a\ few\ tests,\ modify\ the\ setup\ slightly,\ run\ a\ few\ more\ tests,\ modify\ the\ setup\ again,\ and\ so\ on.\ If\ you\ do\ this,\ it\ will\ be\ hard\ for\ people\ to\ figure\ out\ what\ the\ setup\ is\ at\ any\ given\ point\ and\ when\ they\ add\ tests\ later\ they\ are\ likely\ to\ break\ the\ setup.\n\n'''SECTION\ 9'''\n\n''Miscellaneous''\n\n'''SECTION\ 9.1'''\n\n''Porting\ Issues''\n\nWriting\ portable\ scripts\ in\ Tcl\ is\ actually\ quite\ easy\ as\ Tcl\ itself\ is\ quite\ portable.\ However,\ issues\ do\ arise\ that\ may\ require\ writing\ platform\ specific\ code.\ To\ conditionalize\ your\ code\ in\ this\ manner\ you\ should\ use\ the\ tcl_platform\ array\ to\ determine\ platform\ specific\ differences.\ You\ should\ avoid\ the\ use\ of\ the\ env\ variable\ unless\ you\ have\ already\ determined\ the\ platform\ you\ are\ running\ on\ via\ the\ tcl_platform\ array.\ \n\nAs\ Tcl/Tk\ has\ become\ more\ cross\ platform\ we\ have\ added\ commands\ that\ aid\ in\ making\ your\ code\ more\ portable.\ The\ most\ common\ porting\ mistakes\ result\ from\ assumptions\ about\ file\ names\ and\ locations.\ To\ avoid\ such\ mistakes\ always\ use\ the\ file\ join\ command\ and\nlist\ commands\ so\ that\ you\ will\ handle\ different\ file\ separation\ characters\ or\ spaces\ in\ file\ names.\ In\ Tk,\ you\ should\ always\ use\ provided\ high\ level\ dialog\ boxes\ instead\ or\ creating\ your\ own.\ The\ font\ and\ menu\ commands\ has\ also\ be\ revamped\ to\ make\ writing\ cross-platform\ code\ easier.\n\n'''SECTION\ 9.2'''\n\n''Changes\ files''\n\nEach\ package\ should\ contain\ a\ file\ named\ changes\ that\ keeps\ a\ log\ of\ all\ significant\ changes\ made\ to\ the\ package.\ The\ changes\ file\ provides\ a\ way\ for\ users\ to\ find\ out\ what's\ new\ in\ each\ new\ release,\ what\ bugs\ have\ been\ fixed,\ and\ what\ compatibility\ problems\ might\ be\ introduced\ by\ the\ new\ release.\ The\ changes\ file\ should\ be\ in\ chronological\ order.\ Just\ add\ short\ blurbs\ to\ it\ each\ time\ you\ make\ a\ change.\ Here\ is\ a\ sample\ from\ the\ Tk\ changes\ file:\n\n\ 5/19/94\ (bug\ fix)\ Canvases\ didn't\ generate\ proper\ Postscript\ for\ stippled\ text.\ (RJ)\n\ 5/20/94\ (new\ feature)\ Added\ \"bell\"\ command\ to\ ring\ the\ display's\ bell.\ (JO)\n\ 5/26/94\ (feature\ removed)\ Removed\ support\ for\ \"fill\"\ justify\ mode\ from\ Tk_GetJustify.\ (SS)\n\n***\ POTENTIAL\ INCOMPATIBILITY\ ***\nThe\ entries\ in\ the\ changes\ file\ can\ be\ relatively\ terse\;\ once\ someone\ finds\ a\ change\ that\ is\ relevant,\ they\ can\ always\ go\ to\ the\ manual\ entries\ or\ code\ to\ find\ out\ more\ about\ it.\ Be\ sure\ to\ highlight\ changes\ that\ cause\ compatibility\ problems,\ so\ people\ can\ scan\ the\ changes\ file\ quickly\ to\ locate\ the\ incompatibilities.\ Also\ be\ sure\ to\ add\ your\ initials\ to\ the\ entry\ so\ that\ people\ scanning\ the\ log\ will\ know\ who\ made\ a\ particular\ change.\n\n----\n\[Lars\ H\]:\ It\ says\ above\ ''Continuation\ lines\ are\ indented\ 8\ spaces''.\ I\ can't\ recall\ ever\ seeing\ such\ indents\ for\ continuations\;\ 2\ spaces\ seem\ far\ more\ common...\ Is\ this\ a\ typo\ or\ a\ guideline\ that\ the\ community\ ignored?\n\n\[LV\]\ To\ be\ honest,\ the\ primary\ place\ that\ the\ style\ guidelines\ is\nexpected\ to\ be\ followed\ is\ the\ core\ distribution.\ \ However,\ the\nguidelines\ are\ useful\ to\ any\ other\ Tcl\ developer\ as\ well.\nAlso\ note\ that,\ as\ ''guidelines''\ these\ are\ just\ suggestions\ that\ were\nmade,\ sometimes\ arbitrarily,\ so\ that\ people\ who\ want\ or\ need\ a\ standard\nhave\ something\ against\ which\ to\ work.\ \ To\ say\ ''ignored''\ makes\ it\nsound\ as\ some\ sort\ of\ rebellion\;\ I\ suspect\ it\ is\ more\ a\ matter\ of\ many\ndevelopers\ not\ having\ read\ the\ guidelines,\ or\ at\ least\ not\ recently.\n\n''\[escargo\]\ 9\ Apr\ 2005''\ -\ Personally\ I\ find\ indents\ of\ 2\ too\ few\ and\ 8\ too\ many.\ I\ usually\ use\ 4\nand\ get\ support\ for\ this\ from\ \[emacs\]\ and\ \[ASED\].\n\n\[RLH\]\ -\ Ruby\ is\ the\ only\ language\ that\ I\ have\ seen\ that\ has\ ''standardized''\ on\ 2\ spaces.\ I\ agree\ on\ 4\ and\ if\ you\ noticed\ all\ the\ examples\ are\ indented\ with\ 4\ spaces\ as\ well.\n\n\[Lars\ H\]:\ Note\ to\ '''RLH''',\ and\ possibly\ '''escargo'''\ also:\ The\ issue\ was\ ''continuation''\ indentations,\ i.e.,\ those\ following\ a\ backslash-newline\ combination.\ AFAICT\ there\ are\ no\ examples\ of\ these\ above.\ \[RLH\]\ -\ Ah!\ Then\ '''is'''\ 8\ the\ norm?\ \[escargo\]\ -\ I\ just\ ran\ tests\;\ \[emacs\]\ in\ Tcl\ mode\ did\ 4\;\ \[ASED\]\ does\ 8.\ I\ don't\ tend\nto\ change\ things\ manually,\ so\ I\ live\ with\ whatever\ the\ editor\ supports.\ \ \[aricb\]:\ FWIW,\ the\ default\ Tcl\ mode\ on\ my\ Emacs\ installation\ on\ Windows\ (20.7.1)\ indents\ continuation\ lines\ 8\ spaces.\n\n\[AET\]\ 11apr05\ I\ seem\ to\ remember\ (it's\ a\ long\ time\ since\ I\ read\ this)\ that\ the\ point\ was\ to\ have\ DOUBLE\ the\ indent\ (whatever\ you\ use)\ for\ line\ continuation\ to\ differentiate\ them\ from\ one-line\ statements.\ \ \n\n\[HE\]\ 23Jul06\ I\ prefer\ the\ use\ of\ tabs\ to\ indent\ lines.\ This\ has\ some\ advantages\ at\ least\ for\ me:\n\ \ \ *\ Use\ the\ identwidth\ you\ like:\ Most\ editors\ use\ tabs\ 8\ space\ wide.\ If\ the\ editor\ let\ you\ justify\ the\ tabs\ width,\ you\ can\ display\ the\ indents\ like\ you\ want.\ For\ example\ on\ win32\ I\ often\ use\ notepad\ with\ tabs\ =\ 8\ spaces.\ On\ \[pocketPC\]\ I\ prefer\ tabs\ =\ 2\ spaces.\n\ \ \ *\ Tabs\ saves\ memory.\ A\ file\ with\ 500\ lines\ has\ 500\ and\ more\ indents.\ 500\ Indents\ =\ 4\ *\ 500\ spaces\ =\ 2000\ characters.\ With\ tabs\ this\ are\ only\ 500\ characters\ (500\ indents\ =\ 500\ tabs).\ (\[NullGravy\]\ Long\ ago\ this\ made\ sense\ but\ in\ an\ era\ of\ 1Tb\ disks\ for\ <\ £200\ it\ is\ a\ false\ economy.)\n\nI\ use\ the\ following\ rules\ for\ tabs:\n\ \ \ *\ Use\ tabs\ for\ indent.\ \n\ \ \ *\ Fot\ every\ level\ of\ indent\ use\ one\ tab.\n\ \ \ *\ Every\ line\ continuation\ ident\ for\ two\ level.\n\ \ \ *\ Indents\ inside\ comments:\ A\ hashmark\ followed\ by\ tabs.\n\ \ \ *\ Never\ use\ tabs\ inside\ a\ line.\ To\ align\ codefragments\ use\ spaces.\ Reason:\ If\ the\ reader\ use\ an\ alternative\ tabswidth,\ the\ alignment\ is\ broken.\n\nBy\ the\ way.\ The\ original\ tcl/tk\ code\ uses\ a\ mix\ of\ spaces\ and\ tabs\ for\ indent:\n\ \ \ *\ First\ indent\ =\ 4\ spaces\n\ \ \ *\ Second\ indent\ =\ 1\ tab\n\ \ \ *\ Third\ indent\ =\ 1\ tab\ and\ 4\ spaces\n\ \ \ *\ Fourth\ indent\ =\ 2\ tabs\n\ \ \ *\ ...\n\n\[NullGravy\]\ Which\ is\ why\ it\ is\ always\ better\ to\ map\ tabs\ to\ spaces\ on\ input\ -\ otherwise\ someone\ with\ tabs\ set\ at\ anything\ other\ than\ 8\ will\ not\ see\ the\ code\ line\ up\ properly.This\ was\ the\ way\ people\ used\ to\ set\ up\ vi\ for\ the\ space\ reasons\ given\ above).\ In\ my\ experience\ the\ system\ breaks\ down\ badly\ when\ you\ start\ modifying\ code\ obtained\ from\ different\ sources\ with\ different\ ideas\ about\ how\ wide\ a\ tab\ is.\ Also\ the\ most\ basic\ viewers\ (e.g.\ cat\ or\ type)\ will\ ALWAYS\ see\ tabs\ as\ 8\ characters.\n\n----\n\[Agent\]:\ I\ like\ the\ idea\ of\ naming\ commands\ with\ hyphens,\ e.g.\n\ proc\ parse-arguments\ \{\}\ \{\ ...\ \}\nto\ distinguish\ them\ from\ variables\ (which\ of\ course\ must\ use\ underscores\ or\ camel-case).\n\n\[DKF\]:\ Except\ that\ nearly\ all\ valid\ procedure\ names\ are\ also\ valid\ variable\ names\ (the\ exception\ are\ things\ that\ work\ out\ to\ be\ invalid\ array\ references).\ OK,\ the\ '''\$...'''\ syntax\ can't\ handle\ them\ all,\ but\ \[set\]\ can.\n\n\[AMG\]:\ What\ about\ single-word\ command\ names?\ \ (That\ would\ be\ the\ majority,\ in\ my\ experience.)\ \ And\ why\ is\ it\ necessary\ to\ make\ a\ distinction?\ \ It\ is\ not\ only\ legal\ but\ also\ sometimes\ useful\ to\ give\ a\ command\ and\ a\ variable\ the\ same\ name.\ \ See\ \[Gadgets\].\n\n\[Agent\]:\ Well,\ a\ style\ guide\ isn't\ a\ set\ of\ absolute\ rules.\ If\ you\ find\ it\ useful\ to\ give\ a\ command\ and\ variable\ the\ same\ name,\ then\ do\ so.\ Single-word\ command\ names\ are\ usually\ imperative-case\ verbs,\ which\ distinguish\ themselves\ from\ variables.\ \[DKF\],\ I\ don't\ understand\ your\ point.\ Variables\ ''can''\ be\ named\ using\ hyphens\ or\ whatever,\ but\ ''should''\ only\ be\ named\ with\ camel-case\ and\ underscores\ so\ they\ are\ easy\ to\ use\ with\ '''\$'''.\ But,\ as\ commands\ aren't\ used\ with\ '''\$''',\ command\ naming\ need\ not\ restrict\ itself\ to\ camel-case\ and\ underscores,\ so\ that\ affords\ an\ way\ to\ distinguish\ between\ them.\n\n----\n'''CHANGES\ TO\ DOCUMENT'''\n\n\ \ \ *\ \[RLH\]\ -\ Does\ the\ SpecTcl\ stuff\ need\ to\ be\ stripped\ out\ and\ changed?\n\n''Example:''\ 2005-04-11:\ Changed\ the\ blah\ blah\ section\ to\ more\ accurately\ reflect\ the\ current\ accepted\ practice\ with\ foobar.\ \[RLH\]\n\n2005-April-12:\ Changed\ Section\ 2,\ executable\ files\ so\ that\ the\ info\ about\ Macintosh\ is\ couched\ in\ terms\ of\ the\ days\ before\ MacOS\ X.\n\n2005-April-14:\ Did\ some\ formatting\ to\ make\ it\ more\ like\ the\ original.\n\n----\n'''\[hmk\]\ -\ 2010-05-25\ 17:50:45'''\n\nThe\ \"file\ header\"\ in\ this\ wiki\ article\ appears\ to\ be\ different\ from\ this\ article\ from\ 2009:\ http://www.tcl.tk/cgi-bin/tct/tip/352.html\ which\ is\ the\ correct\ way?\n\n======\n\n<<categories>>\ Category\ Tutorial} CALL {my revision {Tcl Style Guide}} CALL {::oo::Obj821184 process revision/Tcl+Style+Guide} CALL {::oo::Obj821182 process}

-errorcode

NONE

-errorinfo

Unknow state transition: LINE -> END
    while executing
"error $msg"
    (class "::Wiki" method "render_wikit" line 6)
    invoked from within
"my render_$default_markup $N $C $mkup_rendering_engine"
    (class "::Wiki" method "render" line 8)
    invoked from within
"my render $name $C"
    (class "::Wiki" method "revision" line 31)
    invoked from within
"my revision $page"
    (class "::Wiki" method "process" line 56)
    invoked from within
"$server process [string trim $uri /]"

-errorline

4