Информация для этой статьи была взята из открытых источников, в том числе использовался англоязычный гайд по правильному оформлению кода от одного из контрибьюторов LuaRocks Hisham Muhammad. Данная статья имеет рекомендательный характер и будет полезна к прочтению теми разработчиками, которые предпочитают разрабатывать скрипты с открытым исходным кодом, а также тем разработчикам, которые работают в команде с другими разработчиками. Качественная разработка начинается с порядка в коде.
Изначально Lua не имеет практически никаких требований и стандартов написания кода, так что действительно можно сказать, что любой рабочий код будет считаться правильным. Но это не совсем правильный подход к работе и каких-никаких стандартов нужно придерживаться как минимум для того, чтобы понимать свой код даже через какое-то время после его фактического написания. Как уже было сказано, это исключительно ваше дело, но если вы собираетесь выкладывать код на всеобщее обозрение - позаботьтесь, чтобы он был читаемый и его можно было понять: правильно расставленной табуляции будет недостаточно - важно и то, как вы строите свой скрипт - как в коде располагаются элементы.
Чтобы не придумывать новые стандарты, мы будем опираться на те, что используются разработчиками достаточно популярных модулей, опубликованных на LuaRocks. Думаю, что это будет правильно, ведь за всеми этими модулями огромное количество рабочего времени, и существование и популярность этих библиотек говорит о том, что они очень успешны.
Главное правило написания правильного кода - его краткость. Строки кода не должны быть километровыми, старайтесь держаться в неких рамках и в случае необходимости переносить части кода на новые строки. Согласитесь, разобраться в длинном условном выражении будет проще, если оно будет поделено на несколько строк вручную, нежели если редактор кода поделит его автоматически, либо вовсе оставит таким длинным, что придётся пользоваться функцией горизонтального пролистывания.
[!] Видите, что кода много - переносите!
Lua поддерживает как одинарные кавычки, так и двойные - их можно использовать во всех случаях, но в больших проектах с типом кавычек начинается полная неразбериха и с этим нужно что-то делать. Второе правило: в любых ситуациях используйте только двойные кавычки - это обусловлено тем, что в большинстве языков программирования двойные кавычки как раз таки используются для обозначения строк, а одинарные для обозначения символов. Одинарные же кавычки можно использовать в тех ситуациях, когда необходимо использовать двойные кавычки внутри строки, либо при необходимости выделить один единственный символ. Возможно, сначала будет непривычно, но со временем этой пройдет.
[!] Двойные кавычки - текст, одинарные - символы и экранирование!
Названия функций могут быть разные: кто-то делит слова нижним подчёркиванием, кто-то делает первую букву слова заглавной, кто-то начинает функцию с маленькой буквы, а кто-то начинает с большой - в конечном итоге код начинает походить на ассорти из разных видов названий и это вызывает некоторые трудности взаимодействия с кодом. Гайд LuaRocks рекомендует использовать стиль разделения слов в функции при помощи нижнего подчёркивания. Более того, функции, проверяющие что-либо и возвращающие значение TRUE, либо FALSE рекомендуется называть с префиксом «is» в начале, например, is_available или is_colored. К большим функциям стоит писать пояснение при помощи комментариев: писать необходимо о том, что делает функция, какие аргументы она принимает и что она может вернуть в результате выполнения.
[!] Называть функции стоит через нижнее подчёркивание, также стоит оставлять пояснения!
Что касается таблиц в Lua, то здесь всё просто: если это возможно, используйте, что называется «plain keys», для обращения к таблицам и для записи в них данных. Если необходимо подставить значение из переменной, либо индекс, в таком случае передать его можно через квадратные скобки. Лучше взглянуть на пример взаимодействия:
Табуляция - очень важная вещь, которая обеспечивает читаемость текста. Обычно редакторы кода предлагают размер табуляции либо в два пробела, либо в четыре. Слишком большие размеры табуляции делают код нечитабельным, поэтому предпочтительнее использовать что-то среднее. Варианты в два или три пробела - золотая середина.
Что касается комментариев в коде, то после двух дефисов стоит ставить один пробел и только после него начинать писать комментарий. Если вы используете многострочные комментарии, стоит добавлять один табуляционный отступ и начинать комментарий на новой строке, т.е. не на той, где вы открыли комментарий, пример представлен ниже.
Также не стоит пихать несколько функций в одну строку, язык программирования, конечно, не против такого, но это может ввести в заблуждение. Для каждой функции и объявленной переменной есть своя строка - не волнуйтесь, место не закончится. В этом есть свои плюсы, например, вы сможете хвастаться количеством строк в вашем коде.
Lua позволяет передавать функциям строки без использования круглых скобочек, но это тоже неправильное оформление. Не забывайте ставить скобки, ведь так ваш код становится более читабельным для других пользователей. Также старайтесь передавать только те аргументы, которые действительно используются в функции.
Табуляция в объявляемых переменных для выравнивания операторов для Lua не подходит, не стоит этим заниматься!
Используйте тернарные операторы, если это возможно, чтобы исключать лишние условные выражения. Это очень удобно и практично!
Старайтесь не повторяться в коде: вы всегда можете создать универсальную функцию, которая будет выполнять определенное действие, и в дальнейшем использовать именно эту функцию для достижения своих целей. Совсем необязательно заниматься копированием и вставкой - вы генерируете огромное количество мусора в коде. Если же вы используете что-то лишь один раз наоборот старайтесь не создавать лишнюю функцию, которую вы используете лишь единожды - проще поместить всё в тело родителя.
В статье расписаны все основные моменты. Если вам кажется, что стоило бы что-нибудь добавить, вы можете написать об этом.
Надеюсь, что информация, представленная в этой статье, была вам полезна и вы подметили что-нибудь важное для себя!
Качественное оформление кода в проектах с использованием языка программирования Lua
Изначально Lua не имеет практически никаких требований и стандартов написания кода, так что действительно можно сказать, что любой рабочий код будет считаться правильным. Но это не совсем правильный подход к работе и каких-никаких стандартов нужно придерживаться как минимум для того, чтобы понимать свой код даже через какое-то время после его фактического написания. Как уже было сказано, это исключительно ваше дело, но если вы собираетесь выкладывать код на всеобщее обозрение - позаботьтесь, чтобы он был читаемый и его можно было понять: правильно расставленной табуляции будет недостаточно - важно и то, как вы строите свой скрипт - как в коде располагаются элементы.
Чтобы не придумывать новые стандарты, мы будем опираться на те, что используются разработчиками достаточно популярных модулей, опубликованных на LuaRocks. Думаю, что это будет правильно, ведь за всеми этими модулями огромное количество рабочего времени, и существование и популярность этих библиотек говорит о том, что они очень успешны.
Главное правило написания правильного кода - его краткость. Строки кода не должны быть километровыми, старайтесь держаться в неких рамках и в случае необходимости переносить части кода на новые строки. Согласитесь, разобраться в длинном условном выражении будет проще, если оно будет поделено на несколько строк вручную, нежели если редактор кода поделит его автоматически, либо вовсе оставит таким длинным, что придётся пользоваться функцией горизонтального пролистывания.
[!] Видите, что кода много - переносите!
Lua:
-- Неправильно!
if red and green and blue and gray and black and white and apple and banana and rock and game and script and you and me then
print("Кажется, условие слишком длинное и нечитаемое!")
end
-- Правильно!
if red and green and blue and gray and black and white and
apple and banana and rock and game and script and you and me then
print("Кажется, это больше похоже на правильный вариант!")
endLua поддерживает как одинарные кавычки, так и двойные - их можно использовать во всех случаях, но в больших проектах с типом кавычек начинается полная неразбериха и с этим нужно что-то делать. Второе правило: в любых ситуациях используйте только двойные кавычки - это обусловлено тем, что в большинстве языков программирования двойные кавычки как раз таки используются для обозначения строк, а одинарные для обозначения символов. Одинарные же кавычки можно использовать в тех ситуациях, когда необходимо использовать двойные кавычки внутри строки, либо при необходимости выделить один единственный символ. Возможно, сначала будет непривычно, но со временем этой пройдет.
[!] Двойные кавычки - текст, одинарные - символы и экранирование!
Lua:
local string = "Здравствуйте, это автор этой статьи!"
local quotes = 'Здравствуйте, а вы читали книгу "Гарри Поттер"?'Названия функций могут быть разные: кто-то делит слова нижним подчёркиванием, кто-то делает первую букву слова заглавной, кто-то начинает функцию с маленькой буквы, а кто-то начинает с большой - в конечном итоге код начинает походить на ассорти из разных видов названий и это вызывает некоторые трудности взаимодействия с кодом. Гайд LuaRocks рекомендует использовать стиль разделения слов в функции при помощи нижнего подчёркивания. Более того, функции, проверяющие что-либо и возвращающие значение TRUE, либо FALSE рекомендуется называть с префиксом «is» в начале, например, is_available или is_colored. К большим функциям стоит писать пояснение при помощи комментариев: писать необходимо о том, что делает функция, какие аргументы она принимает и что она может вернуть в результате выполнения.
[!] Называть функции стоит через нижнее подчёркивание, также стоит оставлять пояснения!
Lua:
function set_color(object, color) -- table, integer
function is_colored(object) -- table; return boolean
function get_data(object) -- table; return tableЧто касается таблиц в Lua, то здесь всё просто: если это возможно, используйте, что называется «plain keys», для обращения к таблицам и для записи в них данных. Если необходимо подставить значение из переменной, либо индекс, в таком случае передать его можно через квадратные скобки. Лучше взглянуть на пример взаимодействия:
Lua:
local new_table = {
new_key = "test",
one_two = 15,
four_three = {"good"}
}
print(new_table.new_key)
print(new_table.four_three[1])
local something = "one_two"
print(new_table[something])Табуляция - очень важная вещь, которая обеспечивает читаемость текста. Обычно редакторы кода предлагают размер табуляции либо в два пробела, либо в четыре. Слишком большие размеры табуляции делают код нечитабельным, поэтому предпочтительнее использовать что-то среднее. Варианты в два или три пробела - золотая середина.
Что касается комментариев в коде, то после двух дефисов стоит ставить один пробел и только после него начинать писать комментарий. Если вы используете многострочные комментарии, стоит добавлять один табуляционный отступ и начинать комментарий на новой строке, т.е. не на той, где вы открыли комментарий, пример представлен ниже.
Lua:
-- Это однострочный комментарий, написанный ПРАВИЛЬНО!
--Это однострочный комментарий, он НЕПРАВИЛЬНЫЙ!
-- Это однострочный комментарий, он тоже НЕПРАВИЛЬНЫЙ!
--[[
Это многострочный комментарий, написанный ПРАВИЛЬНО.
Использована табуляция, комментарий на новой строке
]]
--[[ Это НЕПРАВИЛЬНОЕ использование комментария ]]
--[[ Так писать комментарии тоже не стоит
Это НЕПРАВИЛЬНЫЙ способ написания комментариев! ]]Также не стоит пихать несколько функций в одну строку, язык программирования, конечно, не против такого, но это может ввести в заблуждение. Для каждой функции и объявленной переменной есть своя строка - не волнуйтесь, место не закончится. В этом есть свои плюсы, например, вы сможете хвастаться количеством строк в вашем коде.
Lua:
-- Так делать НЕ НУЖНО!
local hello = "world"; print(hello)
-- А вот так можно
local hello = "world"
print(hello)Lua позволяет передавать функциям строки без использования круглых скобочек, но это тоже неправильное оформление. Не забывайте ставить скобки, ведь так ваш код становится более читабельным для других пользователей. Также старайтесь передавать только те аргументы, которые действительно используются в функции.
Lua:
require "socket" -- так делать НЕ СТОИТ!
require("socket") -- а вот так выглядит неплохоТабуляция в объявляемых переменных для выравнивания операторов для Lua не подходит, не стоит этим заниматься!
Lua:
-- Это плохой вариант!
local apple = true
local fruit_long_var = false
-- Это хороший вариант!
local apple = true
local fruit_long_var = falseИспользуйте тернарные операторы, если это возможно, чтобы исключать лишние условные выражения. Это очень удобно и практично!
Lua:
-- Хороший вариант!
local content = false
print(content and "Available" or "Not available")
-- Плохой вариант!
local content = false
if content then
print("Available")
else
print("Not available")
endСтарайтесь не повторяться в коде: вы всегда можете создать универсальную функцию, которая будет выполнять определенное действие, и в дальнейшем использовать именно эту функцию для достижения своих целей. Совсем необязательно заниматься копированием и вставкой - вы генерируете огромное количество мусора в коде. Если же вы используете что-то лишь один раз наоборот старайтесь не создавать лишнюю функцию, которую вы используете лишь единожды - проще поместить всё в тело родителя.
Lua:
-- Неправильный вариант!
local file = io.open("source.txt", "r")
local data = file:read("*all")
file:close()
file = io.open("file.txt", "r")
local data2 = file:read("*all")
file:close()
-- Правильный вариант!
local function read_file(filepath)
local file = io.open(filepath, "r")
local data = file:read("*all")
file:close()
return data
end
local data = read_file("source.txt")
local data2 = read_file("file.txt")В статье расписаны все основные моменты. Если вам кажется, что стоило бы что-нибудь добавить, вы можете написать об этом.
Надеюсь, что информация, представленная в этой статье, была вам полезна и вы подметили что-нибудь важное для себя!
