[opinion][Research] API design lazarus / 8-Other ---------------------------------------------------------------------- Ñuño_Martínez · 2021-06-04 10:08 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  [Select][+][-]window.onload = function(){var x1 = document.getElementById("main_content_section"); if (x1) { var x = document.getElementsByClassName("geshi");for (var i = 0; i 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  [Select][+][-]window.onload = function(){var x1 = document.getElementById("main_content_section"); if (x1) { var x = document.getElementsByClassName("geshi");for (var i = 0; i 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 · 2021-06-04 10:19 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 · 2021-06-04 10:29 Quote from: denis.totoliciu on June 04, 2021, 12:19:23 pmThis style of writing code is similar to using classes. 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 · 2021-06-04 10:30 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? 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 · 2021-06-04 10:52 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... ---------------------------------------------------------------------- munair · 2021-06-04 10:57 If I'm not mistaken the pascal compiler takes the first unit it comes across that holds the referred procedure. If the programmer refers to the same procedure from another unit, the unit must be used as prefix. In small projects this may seem trivial, but even then conflicts with libraries can result in unexpected compiler complaints or even unexpected outcomes. ---------------------------------------------------------------------- 440bx · 2021-06-04 10:59 Wouldn't using the unit name create a hindrance with Codetools ? ..  it seems like it would get in the way of codetools being really helpful since it will display everything that is visible in the unit every time the unit name is typed (i.e, too many choices, loss of practicality.) ---------------------------------------------------------------------- Ñuño_Martínez · 2021-06-05 09:46 Quote from: munair on June 04, 2021, 12:57:50 pmIf I'm not mistaken the pascal compiler takes the first unit it comes across that holds the referred procedure. If the programmer refers to the same procedure from another unit, the unit must be used as prefix. In small projects this may seem trivial, but even then conflicts with libraries can result in unexpected compiler complaints or even unexpected outcomes. Yep, I know.  That's just why I'm asking for opinion.  Also I think people isn't aware of modern Pascal's moduleness.  I always find it awesome and underrated,  and I don't understand why to add namespaces: units are namespaces by their own! Quote from: 440bx on June 04, 2021, 12:59:54 pmWouldn't using the unit name create a hindrance with Codetools ? ..  it seems like it would get in the way of codetools being really helpful since it will display everything that is visible in the unit every time the unit name is typed (i.e, too many choices, loss of practicality.) I mostly use Vim so... ---------------------------------------------------------------------- lucamar · 2021-06-05 14:59 Quote from: Ñuño_Martínez on June 05, 2021, 11:46:09 am[...] I don't understand why to add namespaces: units are namespaces by their own! Namespaces are meant to take that concept (SomeUnit.SomeProc) one step above and be able to use same-named units (say, from two different packages) and resolve which is used. Say, for example, when you want to have a globals or a StrConst unit; it's to difficult to find a more expressive or appropiate name for those, but it's fine if you can refer to: MyVeryOwnPackage.Globals ---------------------------------------------------------------------- Ñuño_Martínez · 2021-06-05 17:59 I didn't know that about namespaces. I thought it was just add a new level. Interesting.