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