docs/doxygen/mainpages/strategies.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        strategies.h
   3 // Purpose:     Strategies page of the Doxygen manual
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11
  12 @page page_strategies Programming strategies
  13
  14 This chapter is intended to list strategies that may be useful when
  15 writing and debugging wxWidgets programs. If you have any good tips,
  16 please submit them for inclusion here.
  17
  18 @li @ref page_strategies_reducingerr
  19 @li @ref page_strategies_portability
  20 @li @ref page_strategies_debug
  21
  22
  23 <hr>
  24
  25
  26 @section page_strategies_reducingerr Strategies for reducing programming errors
  27
  28 @subsection page_strategies_reducingerr_useassert Use ASSERT
  29
  30 It is good practice to use ASSERT statements liberally, that check for conditions
  31 that should or should not hold, and print out appropriate error messages.
  32
  33 These can be compiled out of a non-debugging version of wxWidgets
  34 and your application. Using ASSERT is an example of `defensive programming':
  35 it can alert you to problems later on.
  36
  37 See wxASSERT for more info.
  38
  39 @subsection page_strategies_reducingerr_usewxstring Use wxString in preference to character arrays
  40
  41 Using wxString can be much safer and more convenient than using wxChar *.
  42
  43 You can reduce the possibility of memory leaks substantially, and it is much more
  44 convenient to use the overloaded operators than functions such as @c strcmp.
  45 wxString won't add a significant overhead to your program; the overhead is compensated
  46 for by easier manipulation (which means less code).
  47
  48 The same goes for other data types: use classes wherever possible.
  49
  50
  51
  52 @section page_strategies_portability Strategies for portability
  53
  54 @subsection page_strategies_portability_usesizers Use sizers
  55
  56 Don't use absolute panel item positioning if you can avoid it. Different GUIs have
  57 very differently sized panel items. Consider using the @ref overview_sizer instead.
  58
  59 @subsection page_strategies_portability_useresources Use wxWidgets resource files
  60
  61 Use .xrc (wxWidgets resource files) where possible, because they can be easily changed
  62 independently of source code. See the @ref overview_xrc for more info.
  63
  64
  65
  66 @section page_strategies_debug Strategies for debugging
  67
  68 @subsection page_strategies_debug_positivethinking Positive thinking
  69
  70 It is common to blow up the problem in one's imagination, so that it seems to threaten
  71 weeks, months or even years of work. The problem you face may seem insurmountable:
  72 but almost never is. Once you have been programming for some time, you will be able
  73 to remember similar incidents that threw you into the depths of despair. But
  74 remember, you always solved the problem, somehow!
  75
  76 Perseverance is often the key, even though a seemingly trivial problem
  77 can take an apparently inordinate amount of time to solve. In the end,
  78 you will probably wonder why you worried so much. That's not to say it
  79 isn't painful at the time. Try not to worry -- there are many more important
  80 things in life.
  81
  82 @subsection page_strategies_debug_simplifyproblem Simplify the problem
  83
  84 Reduce the code exhibiting the problem to the smallest program possible
  85 that exhibits the problem. If it is not possible to reduce a large and
  86 complex program to a very small program, then try to ensure your code
  87 doesn't hide the problem (you may have attempted to minimize the problem
  88 in some way: but now you want to expose it).
  89
  90 With luck, you can add a small amount of code that causes the program
  91 to go from functioning to non-functioning state. This should give a clue
  92 to the problem. In some cases though, such as memory leaks or wrong
  93 deallocation, this can still give totally spurious results!
  94
  95 @subsection page_strategies_debug_usedebugger Use a debugger
  96
  97 This sounds like facetious advice, but it is surprising how often people
  98 don't use a debugger. Often it is an overhead to install or learn how to
  99 use a debugger, but it really is essential for anything but the most
 100 trivial programs.
 101
 102 @subsection page_strategies_debug_uselogging Use logging functions
 103
 104 There is a variety of logging functions that you can use in your program:
 105 see @ref group_funcmacro_log.
 106
 107 Using tracing statements may be more convenient than using the debugger
 108 in some circumstances (such as when your debugger doesn't support a lot
 109 of debugging code, or you wish to print a bunch of variables).
 110
 111 @subsection page_strategies_debug_usedebuggingfacilities Use the wxWidgets debugging facilities
 112
 113 You can use wxDebugContext to check for
 114 memory leaks and corrupt memory: in fact in debugging mode, wxWidgets will
 115 automatically check for memory leaks at the end of the program if wxWidgets is suitably
 116 configured. Depending on the operating system and compiler, more or less
 117 specific information about the problem will be logged.
 118
 119 You should also use @ref group_funcmacro_debugging as part of a `defensive programming' strategy,
 120 scattering wxASSERTs liberally to test for problems in your code as early as possible.
 121 Forward thinking will save a surprising amount of time in the long run.
 122
 123 See the @ref overview_debugging for further information.
 124
 125 */