discussão sobre organização das libs internas da engine

[RodrigoDornelles]

não sabiamos o nome da engine nos primeiros 4 meses de projeto, eu apenas estava trabalhando em novas features e conceitos, mas estava precisando diferenciar libs padrões do lua de uma lib que fosse para própria engine com nome semelhante, resolvi como easteregg chamar de zeebo_math uma das primeiras que foi desenvolvida.

Agora o projeto está maior e existe algumas categorias de libs internas, mas sem uma nomeclatura padronizada, cada core as vezes da nome diferente para mesma lib, e isso está deixando o código bagunçado.

seria legal ter um padrão de como chamar cada lib.

• cli (dedicadas apenas ao uso da command line)
• common (libs que são de uso comum entre a engine e a CLI)
• draw (libs de apoio para renderização de novo objetos)
• engine (libs em geral utilizado por todos todos os cores da engine)
• object (libs que criam valores padrões e esquematicos importantes)
• protocol (componentes usados pelas libs para comportamentos especificos em cada plataforma)
  • note que aqui não existe uma padronização de como o modulo deve ser exportado
• util (libs genericas como construtores de string e outros utilitários)

existe basicamente 2 padrões de imports que trabalho, algumas libs podem ter ambos.

local P = {
  event_bus = event_bus,
  install = install
}

o outro padrão é:

local P = {
  func_a = func_a,
  func_b = func_b,
  func_c = func_c
}

mas não existe nada que seja mandatório, então tu pode encontrar qualquer caso nas pastas, o padrão {install,event_bus} esta presente em todas que são consideradas modulos e intageragem com event loop ou api std da engine.

[lnpotter]

Acho uma boa ideia padronizar pois ao meu ver só facilita para quem usa e quem mantém, também sugiro usarmos alguma ferramenta para lint, seja luacheck, pra verificar variáveis globais, dead code (código que não é utilizado), também há luaformat, para indentação, e selene, que ao meu ver pode ajudar bastante, principalmente no estilo e uso das funções; quanto a definição das categorias, para mim está ótimo e de fácil compreensão

Uma ideia que tive quanto aos imports, foi um namespace centralizado, que ao meu ver poderia clarear melhor e dar um padrão lógico nas importações dos módulos, segue um exemplo:

local P = {
  cli = {
    cmd_parser = require("cli.cmd_parser"),
    cmd_runner = require("cli.cmd_runner")
  },
  draw = {
    object_renderer = require("draw.object_renderer")
  },
  util = {
    string_util = require("util.string_util"),
    table_util = require("util.table_util")
  }
}

[lnpotter]

Pelo que entendi, daria então para adotarmos um padrão de sufixo/prefixo consistente onde nós definiríamos como se chamaria bibliotecas internas da engine, ou bibliotecas externas, um exemplo:

• Manter o prefixo engine_ para todos os módulos que pertencem à engine;
• Separar diferentes tipos de funcionalidades com sufixos descritivos;
• Utilizar um prefixo lib_ outro para bibliotecas de terceiros;
• Para bibliotecas relacionadas a protocolos e suas aplicações específicas, podemos usar um que reflita seu uso, ex.: protocol_ e app_

Exemplos in-code:

local engine_draw_fps = require('src/lib/draw/fps')
local engine_draw_poly = require('src/lib/draw/poly')
local engine_protocol_http = require('src/lib/protocol/http_ginga')
local lib_csv = require('src/third_party/csv/rodrigodornelles')
local lib_json = require('src/third_party/json/rxi')

Ou então, fazermos uso de documentação das variáveis locais, vide:

-- Engine modules
local engine_protocol_http = require('src/lib/protocol/http_ginga')   -- HTTP Protocol implementation - Used for [...]
local engine_encoder = require('src/lib/engine/encoder')                   -- Engine encoder functionality - Used for [..]

-- Drawing utilities
local draw_fps = require('src/lib/draw/fps')               -- FPS drawing functionality - Used for [...]
local draw_poly = require('src/lib/draw/poly')           -- Polygon rendering - Used for [...]

Edit: *Considere os diretórios apenas para conhecimento, apenas copiei e colei sem as respectivas alterações citadas no tópico original

[RodrigoDornelles]

estou +_ seguindo esse caminho, no refatoração que estou fazendo na 0.0.8 está ficando assim

local os = require('os')
--
local core_draw = require('src/engine/core/love/draw')
local core_loop = require('src/engine/core/love/loop')
local lib_api_encoder = require('src/lib/engine/api/encoder')
local lib_api_game = require('src/lib/engine/api/game')
local lib_api_hash = require('src/lib/engine/api/hash')
local lib_api_http = require('src/lib/engine/api/http')
local lib_api_i18n = require('src/lib/engine/api/i18n')
local lib_api_key = require('src/lib/engine/api/key')
local lib_api_math = require('src/lib/engine/api/math')
local lib_draw_fps = require('src/lib/engine/draw/fps')
local lib_draw_poly = require('src/lib/engine/draw/poly')
local lib_raw_bus = require('src/lib/engine/raw/bus')
local lib_raw_memory = require('src/lib/engine/raw/memory')
local lib_raw_module = require('src/lib/engine/raw/module')
--
local cfg_json_rxi = require('src/third_party/json/rxi')
local cfg_http_curl_love = require('src/lib/protocol/http_curl_love')
--
local util_arg = require('src/lib/common/args')
local util_lua = require('src/lib/util/lua')
--
local std = require('src/lib/object/std')

[lnpotter]

Parece bom, está mais organizado que atualmente e seguindo esse padrão acredito que facilite bastante na compreensão, só precisaria, dependendo de quais prefixos for utilizar, documentar eles para quem for contribuir posteriormente ou acabar utilizando ela e precise trabalhar com alguma lib interna/externa do projeto

[RodrigoDornelles]

@lnpotter ainda não tenha certaza se vai ficar assim, por exemplo lib_raw_module é usado como modulo pela engine e modulo de game. antes se chamava zeebo_module e a sua lib ficava em zeebo_modue.lib e também o prefixo foi meio no chute, fiz para ficar um pouco menos poior no que estou trabalhando, pois vai ter muito breakchanges na 0.0.8.

[lnpotter]

Acredito que uma boa alternativa seja module_handler (se for gerenciar módulos) pois é de certa forma clara, sem associar ela à uma parte específica do projeto ("engine" ou "game", deixando assim seu uso neutro)
Outra alternativa, caso queira especificar a utilização dela, eu acredito que seria core_module.

Ex.:

-- core_module pode ser substituído por module_handler também
local core_module = {
    function_a = function_a,
    function_b = function_b,
}