1     ' BugsTrace.doc
  2 
  3     ' Snippet BugsTrace.function inserts these two functions.
  4     '   BugsTrace - writes messages to file appdir\bugstrace\bugstrace.txt if it exists
  5     '   BugsTraceFile - is called once by BugsTrace to set the trace status and location
  6  
  7     ' Snippet BugsTrace.call inserts the following code to call BugsTrace.
  8     ' The message can be a literal comment or a variable name plus it's value.
  9         BugsTrace("message")
 10 
 11     ' Also see function BugsTraceCodeSample below in this snippet for sample use
 12     
 13     ' Click UnDo to delete this documentation snippet after reviewing it
 14     
 15     ' Function BugsTrace
 16 
 17         ' Purpose
 18 
 19         ' BugsTrace provides a very lightweight, easily deployed developer message trace capability
 20         ' that is not dependent on the application, language, framework, or runtime tools for use.
 21 
 22         ' Instant BugsTraces can contribute greatly to rapid development, testing, and debugging. 
 23         ' The BugsTrace output only has trace statements and information the developer wanted
 24         ' to include, making it much more easily readable for rapid testing and debugging. 
 25 
 26 
 27         ' For advanced logging and tracing capabilities you can also use standard vendor provided
 28         ' development and deployment context tracing and debugging options.  However those are
 29         ' typically a lot more execution overhead and/or restricted to development context onlys.
 30 
 31         ' BugsTrace supplements and extends other trace and debug capabilities significantly.
 32  
 33         ' Usage
 34 
 35         ' The input is developer coded BugsTrace("I got here") messages to document major program flows.
 36         ' The output is an appended text file bugstrace.txt in an application subdirectory named \bugstrace.
 37         ' The content can include variables, for example BugsTrace("User entered lookup key: " + sKey).
 38 
 39         ' BugsTrace automatically appends the current user logon, timestamp, and elapsed 1/100 seconds.
 40         ' BugsTrace is designed to minimize overhead and avoid having to create any other objects.
 41         ' Since these methods are inserted as a code snippet there are no external dependencies at all.
 42         ' Any exceptions are by design ignored to minimize overhead and absolutely avoid program impacts.
 43 
 44         ' BugsTrace is 'on' if \bugstrace\bugstrace.txt exists and the user has Write access.
 45         ' BugsTrace is 'off' if \bugstrace\bugstrace.txt does not exist or the user has no Write access.
 46         ' 
 47         ' Application and Security Setup
 48         ' 1. Add the BugsTrace.function snippet, normally no changes are needed
 49         '    Add BugsTrace statements sufficient to document the major program flows.
 50         ' 2. Add a subdirectory named \bugstrace under the application run directory.
 51         '    For example: C:\Apps\MyApplication\bugstrace.
 52         ' 3. Create batch file \bugstrace\On.bat with this DOS command:
 53         '      echo BUGSTRACE - STARTED: %DATE% %TIME% by %USERNAME%>bugstrace.txt
 54         ' 4. Create batch file \bugstrace\Off.bat with this DOS command:
 55         '      del bugstrace.txt
 56         ' 5. If you need to trace a deployed copy, restrict \bugstrace Read and Write access to one
 57         '    user or a few users so that when the trace is turned on, only those users will be traced.
 58         '    Also include \bugstrace Read and Write access for authorized support staff and developers.
 59         ' Now it's ready for use by clicking on.bat to create bugstrace.bat and start tracing.
 60         ' 
 61         ' Coding BugsTrace Statements
 62         ' See method BugsTraceSampleUseInAMethod below for examples of recommended use.
 63         ' Add BugsTrace("message") in place of comments at any point as desired by the developer.
 64         ' Recommended locations are start of methods, major logic branches, and critical i/o steps.
 65         ' Simple conventions can aid in readability e.g. a > prefix at method start and < at end.
 66         ' Even a few trace statements will help provide a useful picture of program use case paths.
 67         ' Additional trace statements can be added as needed to help debug difficult use cases.
 68         ' Optionally add snippet 'VersionInfo' and code BugsTrace("===" + sVersionInfo) at program load.
 69         '
 70         ' Tracing 
 71         ' Double-click on.bat and off.bat to create (turn on) and delete (turn off) bugstrace.txt.
 72         ' Use Notepad to open and review or save a copy of \bugstrace\bugstrace.txt at any point.
 73         ' To trace non-Admin users enable Write for a few individuals rather than large groups.
 74 
 75         ' Best Practices for Production
 76         ' For development, leaving a trace 'on' is ok (technically not much overhead).
 77         ' For production and load testing, follow these best practices.
 78         ' Always delete bugstrace.txt when done testing and copy to another location if needed.
 79         ' Always reset Write access to none or Admins only after usage in production contexts.
 80         ' Always store production trace copies in secure locations if they contain sensitive data.
 81 
 82 
 83     ' Function BugsTraceFile
 84 
 85         ' Purpose
 86         ' BugsTraceFile is called once by BugsTrace to check the trace status and location.
 87         ' The default location is file bugstrace.txt in current execution path subdir \bugstrace.
 88         ' The default of using a flat file offers many advantages for simplicity, configuration, viewing,
 89         ' toggling independent of app, language, and framework, and selective Write access security. 
 90 
 91         ' Overriding the Default Location
 92         ' BugsTrace can be dynamically redirected by simply putting FILE=filespec on line one.
 93         ' For example change on.bat to DOS command 'echo FILE=d:\mydir\bugstrace.txt>bugstrace.txt'.
 94         ' The default location can also be overridden by coding sLocation to use a different filespec. 
 95         ' For example externalize the location a setting in web.config or a registry key.  
 96 
 97       
 98     ' Private Sub BugsTraceCodeSample()
 99 
100         ' Purpose
101 
102         ' These are samples of best practices for using BugsTrace.
103         ' In general, BugsTrace can be used in place of comments.
104 
105         ' Relatively few BugsTrace statements can help quickly verify
106         ' use case workflows and critical variable values, especially
107         ' as compared to stepping through a program in the workbench.
108 
109         ' Add a few more where needed to trace complex use cases or debug problems.
110         ' Avoid BugsTrace statements in heavily repeated loops, instead code before/after.
111         ' This method and set of samples should be deleted after review.
112 
113         ' Best Practice Examples
114         ' In an application startup method, e.g. Form_Load:
115         BugsTrace("=== appname - last maint: date by: who")
116         ' or:
117         BugsTrace(sVersionInfo) ' use with VersionInfo code snippet
118         ' At the start and end of major methods to document use case workflow:
119         BugsTrace(">methodname")
120         ' ....the method code...
121         BugsTrace("<methodname")
122         ' At major code steps and conditional branches:
123         BugsTrace("got here message")
124         ' Before calling other code or accessing data:
125         BugsTrace("get the data, sql:" + sql)
126         ' To document critical variable values:
127         BugsTrace("variable: " + variable.tostring)
128     ' End Sub
129