Самодокументируемые параметры в Lua

Question

Я ищу способ прояснить контракты моих функций Lua. В частности, какие атрибуты там должны иметь параметры.

Чтобы проиллюстрировать мою проблему, некоторые фрагменты кода с типичной структурой моего текущего кода. Функция, которая создает новый "экземпляр" с двумя открытыми функциями.

local function newTextPrinter(color)
    return {
        print = function(textToPrint)
            PrintText(textToPrint, 20, color, 5, 'center');
        end,
        printBig = function(textToPrint)
            PrintText(textToPrint, 30, color, 5, 'center');
        end
    }
end

Функция, которая принимает параметр, который должен иметь одинаковую подпись (или надмножество).

local function printSomeStuff(textPrinter)
    textPrinter.print("some")
    textPrinter.printBig("stuff")
end

Вызов более поздней функции

local textPrinter = newTextPrinter("ffffffff")
printSomeStuff(textPrinter)

Проблема с этим кодом заключается в том, что вы не можете сказать, что textPrinterпараметр предоставляется printSomeStuff должен выглядеть, не глядя на реализацию printSomeStuff, Хотя в этом примере это достаточно просто сделать, это часто не так (и в моем сценарии происходит переключение между файлами). Также нет намека на то, что подходящее значение можно получить через newTextPrinterкроме сходства по названию.

Есть ли способ сделать код более самодокументированным и лучше раскрыть намерения авторов?

Я предпочитаю подход, который является легким и не пытается эмулировать наследование на основе классов. Точно так же код предпочтительнее документации, а в противном случае документация в формате, понятном инструментам, предпочтительнее свободной формы. Ясно, что я могу просто написать комментарий как "параметр textPrinter потребности print а также printBig публичные функции ", однако это очень подвержено ошибкам, если ничего не говорит вам об ошибках, которые вы делаете в документации, или когда вы реорганизуете код и забываете обновить его.

Я использую Lua 5.0 и я довольно плохо знаком с языком.

Answer 1

Да. Во-первых, наименование является ключевым. Далее в комментариях можно описать договор. Далее, количество людей, запрограммированных, отформатированных, помеченных, обработанных и контекстно представленных комментариев. Наконец, гиперссылки в отформатированных комментариях обеспечивают доступ к полной документации.

Существует несколько систем обработки отформатированных комментариев: LuaDoc, LDoc, LDT Documentation Language,…. К сожалению, стандарта нет, и выбор будет в первую очередь зависеть от возможностей IDE пользователя. Некоторые IDE даже помогут автору в форматировании комментариев.

Даже без обработки теги и форматирование - по большей части - улучшают читабельность. Так что пока источник легко всплывает, это помогает.