Lua

本文集文档发布于灏天文库

16.1 代码风格

文档摘要

16.1 代码风格 Lua 代码风格指南：打造优雅、可维护的代码 1. 为什么代码风格如此重要？ 在深入代码风格的具体细节之前，我们先来理解代码风格的重要性： 提升可读性： 一致的代码风格使代码更易于阅读和理解。清晰的结构、恰当的命名和合理的注释，能让开发者快速把握代码意图，降低理解成本。 降低维护成本： 风格统一的代码库更易于维护和修改。当多位开发者参与同一个项目时，统一的代码风格能减少因个人风格差异带来的困扰，降低代码审查和调试的难度。 减少错误： 良好的代码风格有助于减少编码错误。例如，清晰的变量命名可以避免混淆，一致的缩进和空格可以减少语法错误。 促进团队协作： 在团队开发中，统一的代码风格是高效协作的基础。它确保团队成员都能轻松理解和修改彼此的代码，减少沟通成本，提升开发效率。

16.1 代码风格

Lua 代码风格指南：打造优雅、可维护的代码

1. 为什么代码风格如此重要？

在深入代码风格的具体细节之前，我们先来理解代码风格的重要性：

  • 提升可读性： 一致的代码风格使代码更易于阅读和理解。清晰的结构、恰当的命名和合理的注释，能让开发者快速把握代码意图，降低理解成本。

  • 降低维护成本： 风格统一的代码库更易于维护和修改。当多位开发者参与同一个项目时，统一的代码风格能减少因个人风格差异带来的困扰，降低代码审查和调试的难度。

  • 减少错误： 良好的代码风格有助于减少编码错误。例如，清晰的变量命名可以避免混淆，一致的缩进和空格可以减少语法错误。

  • 促进团队协作： 在团队开发中，统一的代码风格是高效协作的基础。它确保团队成员都能轻松理解和修改彼此的代码，减少沟通成本，提升开发效率。

  • 提升代码质量： 注重代码风格往往也意味着注重代码质量。良好的代码风格通常与良好的代码设计和实现紧密相关，共同提升代码的整体质量。

2. 核心原则：一致性、可读性、简洁性

Lua 代码风格的核心原则可以归纳为以下三点：

  • 一致性 (Consistency): 在整个项目、团队甚至个人项目中，代码风格应保持一致。这意味着在命名、缩进、空格、注释等方面都遵循相同的规则。一致性是提升可读性和可维护性的关键。

  • 可读性 (Readability): 代码的首要目的是供人阅读，其次才是机器执行。代码风格应以提升代码的可读性为目标。清晰的结构、简洁的表达、有意义的命名都是提升可读性的重要手段。

  • 简洁性 (Simplicity): Lua 语言本身就以简洁著称。代码风格也应追求简洁，避免过度复杂和冗余的代码。用最少的代码表达清晰的意图，是优秀代码风格的体现。

3. 代码风格实践详解

接下来，我们将深入探讨 Lua 代码风格的各个方面，并提供具体的代码实践和详细解释。

3.1 命名规范 (Naming Conventions)

命名是代码风格中至关重要的一环。好的命名应具有描述性、简洁性和一致性。

3.1.1 变量命名

  • 局部变量 (Local Variables):

    • 使用 lowercase_with_underscores 风格，即小写字母，单词之间用下划线分隔。

    • 使用具有描述性的名称，避免使用单字母或无意义的缩写 (除非在极短的作用域内，例如循环计数器 i, j, k)。

    • 避免使用 Lua 保留关键字作为变量名。

    • 使用清晰的类型前缀 (可选，但推荐)，例如 tbl_users, str_name, num_count, bool_isValid，以增强代码可读性，尤其是在动态类型语言 Lua 中。

    -- 良好的局部变量命名
local user_name = "Alice"
local user_age = 30
local is_active = true
local tbl_products = {}
-- 不推荐的局部变量命名
local a = "Alice" -- 含义不明
local userName = "Alice" -- 风格不一致 (应使用 lowercase_with_underscores)
local user_name_table = {} -- 名称冗余，tbl_products 更简洁明了
​

  • 全局变量 (Global Variables):

    • 尽量避免使用全局变量，除非确实需要在整个程序中共享数据。全局变量容易导致命名冲突和状态污染，降低代码的可维护性。

    • 如果必须使用全局变量，可以使用更具区分度的命名风格，例如 UPPERCASE_WITH_UNDERSCORES 或 添加项目或模块前缀，例如 PROJECT_NAME_GLOBAL_VARIABLE，以减少命名冲突的可能性。

    • 务必使用 local 关键字声明局部变量，避免意外创建全局变量。

    -- 避免使用全局变量 (除非必要)
-- bad practice: accidentally global variable
userName = "Bob" -- 忘记使用 local 关键字，意外创建全局变量
-- 推荐使用局部变量
local local_user_name = "Charlie"
-- 如果必须使用全局变量 (请谨慎使用)
PROJECT_CONFIG_VERSION = "1.0.0" -- 使用 UPPERCASE_WITH_UNDERSCORES 风格
​

  • 常量 (Constants):

    • 使用 UPPERCASE_WITH_UNDERSCORES 风格，即全部大写字母，单词之间用下划线分隔。

    • 常量应该在模块或文件的顶部定义，并使用 local 关键字限定作用域，避免全局污染。

    -- 常量定义示例
local MAX_USERS = 100
local DEFAULT_TIMEOUT = 30
local API_ENDPOINT = "https://api.example.com"
​

3.1.2 函数命名

  • 函数名 (Function Names):

    • 使用 lowercase_with_underscores 风格，与变量命名风格保持一致。

    • 使用动词或动词短语，清晰地表达函数的功能。

    • 避免使用过于宽泛或模糊的函数名。

    • 尽量保持函数名简洁明了，避免过长。

    -- 良好的函数命名
local function calculate_average(numbers)
    -- ...
end
local function is_user_valid(user_id)
    -- ...
end
local function fetch_data_from_api(url)
    -- ...
end
-- 不推荐的函数命名
local function processData(data) -- 功能描述不清晰
local function userCheck(id)    -- 动词使用不清晰
local function getData()        -- 获取什么数据？缺乏上下文
​

3.1.3 表 (Table) 命名

  • 表变量名 (Table Variable Names):

    • 与普通变量命名规则相同，使用 lowercase_with_underscores 风格。

    • 名称应清晰表达表所存储的数据类型或用途。

    • 可以使用类型前缀 tbl_ (可选)。

    -- 表变量命名示例
local tbl_users = {} -- 用户表
local product_list = {} -- 产品列表
local settings_table = {} -- 设置表
​

  • 表字段名 (Table Field Names/Keys):

    • 通常使用 lowercase_with_underscores 风格，与变量和函数命名保持一致。

    • 如果表表示结构化数据 (例如 JSON 对象)，可以考虑使用与数据结构一致的命名风格 (例如 camelCase)，但需要在项目范围内保持一致。

    • 对于表示配置或选项的表，可以使用更简洁的键名，例如缩写或常用术语，但需要保证在上下文中易于理解。

    -- 表字段命名示例 (lowercase_with_underscores)
local user = {
    user_id = 123,
    user_name = "David",
    email_address = "david@example.com"
}
-- 表字段命名示例 (简洁键名，用于配置)
local config = {
    timeout = 60, -- 超时时间 (秒)
    retries = 3,  -- 重试次数
    log_level = "INFO" -- 日志级别
}
​

3.1.4 模块命名

  • 模块文件名:

    • 通常使用 lowercase_with_underscores.lua 风格，与变量和函数命名保持一致，并使用 .lua 扩展名。

    • 文件名应与模块的功能或内容相关。

    • 避免使用与 Lua 标准库模块或其他常用模块重名的文件名。

    -- 模块文件名示例
user_management.lua
data_processing.lua
http_client.lua
​

  • 模块内部导出 (Module Export):

    • 模块导出的函数和变量，其命名规则与普通函数和变量相同，使用 lowercase_with_underscores 风格。

    • 模块的入口点 (通常是一个返回模块表的 require 调用) 可以使用模块文件名 (去除 .lua 扩展名) 作为变量名。

    -- user_management.lua 模块示例
local function create_user(name, email)
    -- ...
end
local function delete_user(user_id)
    -- ...
end
local M = {} -- 模块表
M.create_user = create_user
M.delete_user = delete_user
return M
-- 在其他文件中使用该模块
local user_management = require("user_management")
user_management.create_user("Eve", "eve@example.com")
​

3.2 缩进与空格 (Indentation and Whitespace)

缩进和空格对于代码的可读性至关重要。它们能清晰地展现代码的结构和逻辑关系。

3.2.1 缩进 (Indentation)

  • 使用 4 个空格进行缩进。 这是 Lua 社区广泛接受的标准缩进方式。

  • 避免使用制表符 (Tab) 进行缩进。 不同编辑器对制表符的显示宽度可能不同，容易导致代码在不同环境中显示错乱。

  • 保持一致的缩进风格。 在整个项目中，始终使用 4 个空格进行缩进，避免混合使用空格和制表符，或使用不同数量的空格。

    -- 良好的缩进示例 (4 个空格)
if condition then
    local result = calculate_value()
    if result > 10 then
        print("Result is greater than 10")
    end
    return result
end
-- 不推荐的缩进示例 (制表符或不一致的空格)
if condition then
	local result = calculate_value() -- 使用制表符
  if result > 10 then             -- 不一致的空格 (2 个空格)
    print("Result is greater than 10")
  end
  return result
end
​

3.2.2 空格 (Whitespace)

  • 在二元运算符 (例如 +, -, *, /, =, ==, >, <) 两侧添加空格。 这能提高代码的可读性，使运算符更易于识别。

  • 在逗号 , 之后添加空格。 分隔列表项时，逗号后的空格使代码更清晰。

  • 在花括号 {} 和方括号 [] 内部，以及圆括号 () 内部，通常不添加空格，除非为了提高特定情况下的可读性 (例如，长参数列表)。

  • 在代码块之间、函数之间、逻辑段落之间，可以使用空行进行分隔，提高代码的视觉分隔性。

    -- 良好的空格示例
local sum = a + b
local numbers = {1, 2, 3, 4}
local result = function_call(arg1, arg2, arg3)
if (x > 0 and y < 10) then
    -- ...
end
-- 不推荐的空格示例
local sum=a+b -- 缺少运算符两侧的空格
local numbers = { 1,2,3,4 } -- 花括号内部添加了空格 (通常不推荐)
local result = function_call( arg1 , arg2 , arg3 ) -- 参数列表逗号后缺少空格
if(x>0 and y<10)then -- 圆括号内部和 if/then 关键字周围缺少空格
    -- ...
end
​

3.3 注释 (Comments)

注释是代码的重要组成部分，用于解释代码的功能、逻辑和意图。

  • 注释的目的:

    • 解释代码的功能和目的，尤其是对于复杂或不明显的代码段。

    • 记录代码的设计思路、算法和实现细节。

    • 标记待办事项 (TODO)、缺陷 (FIXME) 或需要改进的地方。

    • 为函数、模块和类 (如果使用面向对象编程) 提供文档。

  • 注释的类型:

    • 单行注释 (--): 用于注释单行代码或在行尾添加简短注释。

    • 多行注释 (--[[ ... -- ]]): 用于注释多行代码块或编写详细的文档注释。

  • 注释的最佳实践:

    • 注释应简洁明了，准确描述代码的意图，避免冗余和模糊的注释。

    • 注释应与代码同步更新，当代码修改时，注释也应相应更新。

    • 注释应注重解释 "为什么 (Why)"，而不是 "是什么 (What)" 和 "如何做 (How)" (代码本身已经说明了 "是什么" 和 "如何做")。 解释代码背后的逻辑和意图比简单描述代码的功能更有价值。

    • 对于公开的函数和模块，应编写清晰的文档注释，说明其功能、参数、返回值和使用方法。 可以使用类似 Markdown 的格式进行文档注释，方便生成文档。

    • 避免过度注释。 清晰的代码本身就是最好的文档。对于简单的、自解释的代码，不一定需要添加注释。

    • 使用英文注释。 即使项目团队主要使用中文，也建议使用英文注释，以提高代码的通用性和可维护性，方便其他开发者理解和贡献代码。

    -- 单行注释示例
local count = 0 -- 初始化计数器
-- 多行注释示例
--[[
这个函数用于计算两个数字的和。
参数：
    a: 第一个数字
    b: 第二个数字
返回值：
    两个数字的和
--]]
local function add(a, b)
    return a + b
end
-- TODO: 优化算法，提高性能
-- FIXME: 修复边界条件错误
-- 良好的注释示例 (解释 "为什么")
-- 为了防止除零错误，在除法之前检查除数是否为零
if divisor ~= 0 then
    local result = dividend / divisor
else
    error("Division by zero")
end
​

3.4 代码结构与组织 (Code Structure and Organization)

良好的代码结构和组织能提高代码的可读性和可维护性，降低代码的复杂度。

3.4.1 函数 (Functions)

  • 函数应保持短小精悍，功能单一。 一个函数只负责完成一个明确的任务，避免函数过于庞大和复杂。

  • 函数应具有清晰的输入和输出。 明确函数的参数和返回值，使函数的功能和使用方式易于理解。

  • 避免函数产生副作用 (side effects)。 函数应尽可能只根据输入参数计算输出结果，避免修改外部状态或全局变量，以提高函数的可预测性和可测试性。

  • 合理使用局部变量，避免全局变量。 函数内部应优先使用局部变量，减少对外部环境的依赖，提高函数的独立性和可复用性。

    -- 良好的函数结构示例
local function calculate_discounted_price(price, discount_rate)
    -- 计算折扣金额
    local discount_amount = price * discount_rate
    -- 计算折扣后价格
    local discounted_price = price - discount_amount
    return discounted_price
end
-- 不推荐的函数结构示例 (功能复杂，副作用)
local total_price = 0 -- 全局变量
local function process_order(order_items)
    for _, item in ipairs(order_items) do
        total_price = total_price + item.price -- 修改全局变量
        -- ... 其他复杂的订单处理逻辑 ...
    end
    print("Total price:", total_price) -- 输出到控制台 (副作用)
end
​

3.4.2 模块 (Modules)

  • 使用模块来组织代码，实现代码的模块化和封装。 将相关功能的代码组织到一个模块中，提高代码的可复用性和可维护性。

  • 模块应具有清晰的接口和职责。 模块应明确导出需要对外提供的函数和变量 (通过模块表返回)，隐藏内部实现细节，降低模块之间的耦合度。

  • 合理划分模块，避免模块过于庞大。 根据功能和逻辑关系，将代码划分为多个模块，每个模块负责一个相对独立的任务。

  • 使用 require 函数加载模块。 在需要使用模块功能的地方，使用 require 函数加载模块，并使用模块名访问模块导出的函数和变量。

    -- 模块结构示例 (假设模块文件名为 math_utils.lua)
-- math_utils.lua 模块
local function add(a, b)
    return a + b
end
local function subtract(a, b)
    return a - b
end
local M = {} -- 模块表
M.add = add
M.subtract = subtract
return M
-- 在其他文件中使用该模块
local math_utils = require("math_utils")
local sum = math_utils.add(10, 5)
local difference = math_utils.subtract(20, 8)
​

3.4.3 控制结构 (Control Structures)

  • if-else 语句:

    • if 条件和 then 关键字应在同一行，else 和 elseif 关键字也应与相应的 if 或 elseif 关键字对齐。

    • 代码块应使用缩进，清晰地表示代码的层次结构。

    -- if-else 语句示例
if condition1 then
    -- 代码块 1
elseif condition2 then
    -- 代码块 2
else
    -- 代码块 3
end
​

  • 循环语句 (for, while, repeat-until):

    • 循环语句的关键字 (for, while, repeat) 和循环条件应在同一行。

    • 循环体代码块应使用缩进。

    -- for 循环示例
for i = 1, 10 do
    -- 循环体代码
end
-- while 循环示例
while condition do
    -- 循环体代码
end
-- repeat-until 循环示例
repeat
    -- 循环体代码
until condition
​

  • do-end 块:

    • do 和 end 关键字用于显式地创建代码块，限制变量的作用域。

    • 可以使用 do-end 块来组织代码，提高代码的可读性和可维护性。

    -- do-end 块示例
do
    local temp_variable = "temporary value"
    -- 在 do-end 块内可以使用 temp_variable
    print(temp_variable)
end
-- 在 do-end 块外无法访问 temp_variable (超出作用域)
-- print(temp_variable) -- 错误：attempt to access a local variable 'temp_variable' (upvalue)
​

3.5 其他代码风格建议

  • 错误处理 (Error Handling):

    • 使用 assert 函数进行断言检查，用于在开发阶段检测程序中的错误。

    • 使用 pcall 函数捕获可能抛出错误的函数调用，进行错误处理，避免程序崩溃。

    • 使用 error 函数抛出自定义错误，并提供清晰的错误信息。

    • 合理处理错误，避免忽略错误或简单地吞噬错误。

  • 代码长度限制:

    • 尽量保持代码行长度不超过 120 个字符，以提高代码在不同显示器上的可读性。

    • 对于过长的代码行，应进行适当的换行和缩进，保持代码的结构清晰。

  • 一致性工具 (Linters and Formatters):

    • 可以使用 Lua 代码风格检查工具 (Linters)，例如 luacheck, lualint 等，自动检查代码是否符合代码风格规范。

    • 可以使用 Lua 代码格式化工具 (Formatters)，例如 stylua 等，自动格式化代码，使其符合统一的代码风格。

    • 在项目中使用 Linter 和 Formatter 可以有效地保证代码风格的一致性，提高代码质量。

发布者: 作者: 转发
评论区 (0)
U
0/500