[Freeciv-Dev] (PR#3423) Clear city description

["Jason Short" <jdorje@xxxxxxxxxxxxxxxxxxxxx>]

[rfalke - Sat Feb 15 11:15:19 2003]:

> On Sat, Feb 15, 2003 at 02:38:23AM -0800, Rafa³ Bursig wrote:
> > >  - the function should be renamed to
> prepare_show_city_descriptions or
> > >  start_show_city_descriptions or something like this
> > I don't care what will be total name of this function but word
> "clear"
> > should be in it, becouse it give you description what this function
> > should do.
> 
> No. This is wrong. This is too gui-sdl centric. With the new function
> we provide a hook which a GUI can use to prepare certain things before
> show_city_descriptions starts. That gui-sdl takes this opportunity to
> clear its old description in this function doesn't belong in the
> common code in the form of the function name.

It is not gui-sdl-centric.  It is very unlikely that any GUI would use
it for anything other than clearing the city descriptions.  Just because
only some GUIs do this does not mean the name is inappropriate (see below).

It is true that this is an arbitrary hook that the GUI can use to do
preparation for show_city_descriptions.  But really all GUI functions
called by the common code are arbitrary hooks - we give them names so
that the GUI author understands what they are intended for, but an
ambitious author often extends them beyond this (generally with mixed
results).

prepare_show_city_descriptions, in particular, is not an especially good
name IMO since show_city_descriptions is mostly used internally in the
drawing code.  It is not called at all by the GUI (although an
enterprising GUI author might want to do so).

However, clear_city_descriptions will have to have different behavior
depending on how the GUI is written.  For a simple 1-buffer system, no
action is needed (since show_city_description is only called after the
underlying map has been redrawn).  For a 2-buffer system (map and
map+desc), a single copy is needed.  For a 3-buffer system (map, desc,
main) it has to clear the buffer.  This behavior may seem arbitrary if
you just consider the name of the function.  And yet, no better name
suggests itself (to me, anyway).

jason