Changes between Version 22 and Version 23 of CodeBestPractices


Ignore:
Timestamp:
2012-12-01 11:18:56 (7 years ago)
Author:
jeroens
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • CodeBestPractices

    v22 v23  
    11= Best practices when coding EwE6 = 
    22This page describes standard solutions for recurring oddities and nasties that we have ran into over the years when building EwE6. 
     3 
     4'' THIS SECTION IS UNDER DEVELOPMENT '' 
    35 
    46The following issues are discussed on this page: 
     
    1719 
    1820---- 
     21 
    1922== Robustness == 
    2023 
     
    2326=== Try / Catch === 
    2427 
    25 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. 
     28Make your code robust to failures by encapsulating big function calls in [http://www.homeandlearn.co.uk/net/nets5p4.html Try / Catch] blocks. Public methods in 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. 
    2629 
    2730Take for instance the code that runs in response to a 'Run' button click on the Run Ecosim form: 
    2831{{{ 
    29         Private Sub OnRun(ByVal sender As System.Object, ByVal e As System.EventArgs) _ 
    30             Handles m_btnRun.Click 
     32Private Sub OnRun(ByVal sender As System.Object, ByVal e As System.EventArgs) _ 
     33   Handles m_btnRun.Click 
    3134 
    32             '''Try''' 
    33                 If Not Me.IsRunning Then 
    34                     Me.m_iTimeSteps = Me.Core.nEcosimTimeSteps 
    35                     Me.m_graph.Refresh() 
    36                     Me.Core.RunEcoSim(AddressOf TimeStepFromEcoSim_handler, True) 
    37                 End If 
    38             '''Catch ex As Exception''' 
    39                 cLog.Write(ex, "form RunEcosim.OnRun") 
    40             '''End Try''' 
     35   Try 
     36      If Not Me.IsRunning Then 
     37         Me.m_iTimeSteps = Me.Core.nEcosimTimeSteps 
     38         Me.m_graph.Refresh() 
     39         Me.Core.RunEcoSim(AddressOf TimeStepFromEcoSim_handler, True) 
     40      End If 
     41   Catch ex As Exception 
     42      cLog.Write(ex, "form RunEcosim.OnRun") 
     43   End Try 
    4144 
    42         End Sub 
     45End Sub 
    4346}}} 
    4447 
     
    4952The 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. 
    5053 
    51 If you strategically encapsulate [#try_/_cath Try / Catch] blocks, why not write the result of the exception to the log file: 
     54If you strategically encapsulate [#try_/_cath Try / Catch] blocks, why not write the result of the exception to the log file, as shown here in the Catch part of the try/catch block: 
     55{{{ 
     56Private Sub OnRun(ByVal sender As System.Object, ByVal e As System.EventArgs) _ 
     57   Handles m_btnRun.Click 
    5258 
    53 Take for instance the code that runs in response to a 'Run' button click on the Run Ecosim form: 
     59   Try 
     60      If Not Me.IsRunning Then 
     61         Me.m_iTimeSteps = Me.Core.nEcosimTimeSteps 
     62         Me.m_graph.Refresh() 
     63         Me.Core.RunEcoSim(AddressOf TimeStepFromEcoSim_handler, True) 
     64      End If 
     65   Catch ex As Exception 
     66      cLog.Write(ex, "form RunEcosim.OnRun") 
     67   End Try 
     68 
     69End Sub 
     70}}} 
     71 
     72=== Assertions === 
     73 
     74Make it a habit to make your code as sound as it can get by testing whether [http://www.homeandlearn.co.uk/net/nets5p1.html your code is properly used]. [http://msdn.microsoft.com/en-us/library/system.diagnostics.debug.assert%28v=vs.71%29.aspx Assertions] are a neat way to slap yourself on the wrist if built-in assumptions in your code are somehow failing. In EwE, we sometimes refer to these checks as ''sanity checks'' ;-) In released versions of EwE assertions will not show up, but they are a good tool to check whether your code is used as it is supposed to while developing. 
     75 
     76To illustrate, does the following code make sense? 
    5477{{{ 
    55         Private Sub OnRun(ByVal sender As System.Object, ByVal e As System.EventArgs) _ 
    56             Handles m_btnRun.Click 
     78Public Function Div(ByVal dividend As Single, ByVal divider As Single) As Single 
    5779 
    58             Try 
    59                 If Not Me.IsRunning Then 
    60                     Me.m_iTimeSteps = Me.Core.nEcosimTimeSteps 
    61                     Me.m_graph.Refresh() 
    62                     Me.Core.RunEcoSim(AddressOf TimeStepFromEcoSim_handler, True) 
    63                 End If 
    64             Catch ex As Exception 
    65                 '''cLog.Write(ex, "form RunEcosim.OnRun")''' 
    66             End Try 
     80   'Sanity checks 
     81   Debug.Assert(dividend <> 0, "Cannot divide by zero") 
    6782 
    68         End Sub 
     83   Return dividend / divider 
     84 
     85End Function 
    6986}}} 
     87 
    7088---- 
    7189