Forum > Other

[opinion][Research] API design

(1/2) > >>

Ñuño_Martínez:
So, I’m rewriting my engine and I’m struggling with API names.

I was using prefixes and suffixes to differentiate the engine and subsystems stuff.  For example, this program for an hypothetical action game:

--- Code: Pascal  [+][-]window.onload = function(){var x1 = document.getElementById("main_content_section"); if (x1) { var x = document.getElementsByClassName("geshi");for (var i = 0; i < x.length; i++) { x[i].style.maxHeight='none'; x[i].style.height = Math.min(x[i].clientHeight+15,306)+'px'; x[i].style.resize = "vertical";}};} ---program Game;   uses    Mingro, mngSprites, Title, Playfield, sysutils;   function Initialize: Boolean;  begin    if mngInit and mngInitializeSprites then    begin      if mngLoadSpriteSheet ('player.spr') then        Exit (True)      else begin        mngLog.Trace (etError, 'Can''t load sprite sheet.');        Exit (False)      end    end    else begin      mngLog.Trace (etError, 'Can''t init engine!');      Exit (False)    end  end; begin  if Initialize then while RunTitle do RunGameend.
What I was thinking is to use the unit name as namespace, so the previous program will look like this:


--- Code: Pascal  [+][-]window.onload = function(){var x1 = document.getElementById("main_content_section"); if (x1) { var x = document.getElementsByClassName("geshi");for (var i = 0; i < x.length; i++) { x[i].style.maxHeight='none'; x[i].style.height = Math.min(x[i].clientHeight+15,306)+'px'; x[i].style.resize = "vertical";}};} ---program Game;   uses    Mingro, mngSprites, Title, Playfield, sysutils;   function Initialize: Boolean;  begin    if Mingro.Initialize and mngSprites.Initialize then      if mngSprites.LoadSheet ('player.spr') then        Exit (True)      else begin        Mingro.Log.Trace (etError, 'Can''t load sprite sheet.');        Exit (False)      end    else begin      Mingro.Log.Trace (etError, 'Can''t init engine!');      Exit (False)    end  end; begin  if Initialize then while Title.Run do Playfield.Runend.
I don’t see that kind of API anywhere but I think it is clean and clear and more appealing than using prefix/sufix to differentiate between subsystems (except the fact that when two units declare an object with same name and you don’t precede it with the unit name, FPC doesn’t warns and picks one resulting in some funny debug sessions).

What do you think about this kind of API?

denis.totoliciu:
It is an interesting point of view and I think it works pretty when you have units that use short names along with structured programming. There are some down factors to using this way of writing source code, but if you keep it simple, it can work well for smaller projects.

This style of writing code is similar to using classes.

MarkMLl:

--- Quote from: denis.totoliciu on June 04, 2021, 12:19:23 pm ---This style of writing code is similar to using classes.

--- End quote ---

In practical terms, the syntax is just about identical whether e.g. mngLog is a unit or is a class. I use that to swap seamlessly between static and dynamic linkage, and have a mostly-completed tool which handles most of the unit-generation work.

MarkMLl

440bx:

--- Quote from: Ñuño_Martínez on June 04, 2021, 12:08:59 pm ---(except the fact that when two units declare an object with same name and you don’t precede it with the unit name, FPC doesn’t warns and picks one resulting in some funny debug sessions).

What do you think about this kind of API?

--- End quote ---
I think you hit the nail on the head about using the unit name.  As you mentioned, if two units declare a function/procedure with the same name, that can create some difficult to find bugs.

Prefixes have a big advantage: unlike unit names, they are not optional and if forgotten, the compiler will usually complain about an unknown identifier.  That makes it much more unlikely to have two different (but unfortunately similar) routines with the same names in different units.

Using prefixes is more robust.



Ñuño_Martínez:
So one yes and one not (just kidding).

The compiler warning issue is what concerns me more, but I still like the idea of using unit names as namespaces...

Navigation

[0] Message Index

[#] Next page

Go to full version