Question

i want to mark a method as obsolete, but Delphi 5 doesn’t have such a feature.

For the sake of an example, here is a made-up method with it’s deprecated and new preferred form:

procedure TStormPeaksQuest.BlowHodirsHorn; overload; //obsolete
procedure TStormPeaksQuest.BlowHodirsHorn(UseProtection: Boolean); overload;

Note: For this hypothetical example, we assume that using the parameterless version is just plain bad. There are problems with not “using protection” – which have no good solution. Nobody likes having to use protection, but nobody wants to not use protection. So we make the caller decide if they want to use protection or not when blowing Hodir’s horn. If we default the parameterless version to continue not using protection:

procedure TStormPeaksQuest.BlowHodirsHorn;
begin
    BlowHodirsHorn(False); //No protection. Bad!
end;

then the developer is at risk of all kinds of nasty stuff. If we force the parameterless version to use protection:

procedure TStormPeaksQuest.BlowHodirsHorn;
begin
    BlowHodirsHorn(True); //Use protection; crash if there isn't any
end;

then there’s a potential for problems if the developer didn’t get any protection, or doesn’t own any.

Now i could rename the obsolete method:

procedure TStormPeaksQuest.BlowHodirsHorn_Deprecatedd; overload; //obsolete
procedure TStormPeaksQuest.BlowHodirsHorn(UseProtection: Boolean); overload;

But that will cause a compile error, and people will bitch at me (and i really don’t want to hear their whining). i want them to get a nag, rather than an actual error.

i thought about adding an assertion:

procedure TStormPeaksQuest.BlowHodirsHorn; //obsolete
begin
   Assert(false, 'TStormPeaksQuest.BlowHodirsHorn is deprecated. Use BlowHodirsHorn(Boolean)');

   ...
end;

But i cannot guarantee that the developer won’t ship a version without assertions, causing a nasty crash for the customer.

i thought about using only throwing an assertion if the developer is debugging:

procedure TStormPeaksQuest.BlowHodirsHorn; //obsolete
begin
   if DebugHook > 0 then
      Assert(false, 'TStormPeaksQuest.BlowHodirsHorn is deprecated. Use BlowHodirsHorn(Boolean)');

   ...
end;

But i really don’t want to be causing a crash at all.

i thought of showing a MessageDlg if they’re in the debugger (which is a technique i’ve done in the past):

procedure TStormPeaksQuest.BlowHodirsHorn; //obsolete
begin
   if DebugHook > 0 then
        MessageDlg('TStormPeaksQuest.BlowHodirsHorn is deprecated. Use BlowHodirsHorn(Boolean)', mtWarning, [mbOk], 0);

   ...
end;

but that is still too disruptive. And it has caused problems where the code is stuck at showing a modal dialog, but the dialog box wasn’t obviously visible.

i was hoping for some sort of warning message that will sit there nagging them – until they gouge their eyes out and finally change their code.

i thought perhaps if i added an unused variable:

procedure TStormPeaksQuest.BlowHodirsHorn; //obsolete
var
   ThisMethodIsObsolete: Boolean;
begin
   ...
end;

i was hoping this would cause a hint only if someone referenced the code. But Delphi shows a hint even if you don’t call actually use the obsolete method.

Can anyone think of anything else?

Answer 1

What I’ve ended up using was a combination of opting into a system where you agree to not have any deprecated code, with output debug strings and breakpoints otherwise.

Like strict html, I’ve created a Strict define.

All the common units have the obsolete code defined out if Strict is defined. That way the developer has agreed that they will not have deprecated code in their project:

{$IFNDEF Strict}
procedure TStormPeaksQuest.BlowHaldirsHorn; overload; //obsolete
{$ENDIF}
procedure TStormPeaksQuest.BlowHaldirsHorn(UseProtection: Boolean); {$IFNDEF Strict}overload;{$ENDIF}


{$IFNDEF Strict}
procedure TStormPeaksQuest.BlowHaldirsHorn; //obsolete
begin
   OutputDebugString(PAnsiChar('TStormPeaksQuest.BlowHaldirsHorn is deprecated. Use BlowHaldirsHorn(Boolean)'));

   //Don't debugbreak without a debugger attached!
   if DebugHook > 0 then
        Windows.DebugBreak;

   ...
end;

So if the developer wants to have proper code, suffering having to perform code-changes when new things are deprecated, they can:

{$DEFINE Strict}

If not, then there will always be an OutputDebugString, and anyone with Debug View can see (even customers). It’s funny to see commercial software (even Microsoft’s) with output debug strings left over.

And finally, if there’s a debugger attached, then they’ll get a debug breakpoint out of nowhere. If anyone asks about, i can take that opportunity to make fun of them.