Changes between Version 20 and Version 21 of CodeBestPractices

Timestamp:

2012-12-01 10:58:06 (11 years ago)

Author:

jeroens

Comment:

--

CodeBestPractices

@@ -6 +6 @@
    * [#try_/_cath Try / Catch and Assertions]
    * Creation and disposal of objects and data
+   * Logging events
  * [#Compatibility Cross-platform compatibility]
    * [#Mono Mono]
@@ -18 +19 @@
 == Robustness ==
 
-=== Try / Catch ==
+Take it from us. Users can find very creative ways to use a software product in ways that a programmer could never, ever have predicted. As such, it is of vital importance that your code is robust to failures, even if you do not know in what ways your product may fail. It's rarely a good think to be caught with your pants down, and this section aims to provide a few simple guidelines.
 
+=== Try / Catch ===
 
+Make your code robust to failures by encapsulating big function calls in [http://www.homeandlearn.co.uk/net/nets5p4.html Try / Catch] blocks. Public methods on public classes are often the entry point to deeper functionality, and placing a Try / Catch inside the public methods is a good way to capture any internal failures within your code. We've done the same in the plug-in framework, where every plug-in point call is wrapped in a Try / Catch block to make sure EwE is not affected by a failing plug-in point or button click.
+
+Take for instance the code that runs in response to a 'Run' button click on the Run Ecosim form:
+{{{
+        Private Sub OnRun(ByVal sender As System.Object, ByVal e As System.EventArgs) _
+            Handles m_btnRun.Click
+
+            Try
+                If Not Me.IsRunning Then
+                    Me.m_iTimeSteps = Me.Core.nEcosimTimeSteps
+                    Me.m_graph.Refresh()
+                    Me.Core.RunEcoSim(AddressOf TimeStepFromEcoSim_handler, True)
+                End If
+            Catch ex As Exception
+                cLog.Write(ex, "form RunEcosim.OnRun")
+            End Try
+
+        End Sub
+}}}
+
+Note that in EwE we prefer not to rely on exceptions for regular error testing. Exception handling is very processor intensive, and a simple [http://www.homeandlearn.co.uk/net/nets1p20.html If / Then] test is endlessly faster than bluntly executing code and waiting for the exceptions to happen. As such, we suggest to only use exceptions to capture unforeseen problems.
+
+=== Logging events ===
+
+The EwE Log file, created and managed by the core, and stored in the Windows application data folder, contains a track list of important actions taken by !EwE in response to user requests and a track record of failures and successes. The purpose of the log is to provide postmortem diagnostics when an error has occurred. You can use the log as well in your plug-ins. Frankly, we think you should, because 
 ----