ddl战士——代码规范

ddl战士 2025-11-25 22:35:54

这个作业属于哪个课程	2501_CS_SE_FZU
这个作业要求在哪里	[ 团队作业—Beta冲刺]https://bbs.csdn.net/topics/620025444
这个作业的目标	代码规范
其他参考文献	《构建之法》、Google Style Guides

Unity Roguelike 项目代码规范
1. 基本目标
2. 基础格式
3. 命名规则
4. 注释与文档
5. 生命周期与职责
6. 序列化与 Inspector
7. 输入
8. 物理与碰撞
9. 战斗与数值
10. 动画
11. UI
12. 资源与内存
13. 日志与调试
14. 错误处理
15. 架构与职责
16. 提交与目录
17. 自测清单（新增/修改功能时）
18. 示例代码片段（风格示范）

Unity Roguelike 项目代码规范

1. 基本目标

统一风格，降低维护成本，便于多人协作与调试。
代码可读、可测、可视化（日志/Gizmos），保持性能与内存安全。

2. 基础格式

统一使用 UTF-8（无 BOM）的编码格式，确保跨平台兼容性；行尾不留空格；换行 \n。
缩进 4 空格；花括号换行（K&R 变体）；每文件单一公开类。
using 顺序：System.* → 第三方 → UnityEngine → UnityEngine.UI → 其他。
文件名 = 公开类/接口/枚举名。

3. 命名规则

类型/枚举/委托：PascalCase；接口前缀 I（保留现有 SM_ 系列）。
字段：camelCase；序列化私有字段 [SerializeField] private；常量 PascalCase 或 UPPER_SNAKE。
布尔：以 is/has/can/should 开头；事件：OnXxx。
Animator 参数：常量化或序列化字段，避免硬编码字符串。
Inspector 暴露的 LayerMask/Prefab/Transform 等必须命名清晰，含用途。

4. 注释与文档

公开类/方法/字段：<summary> 简述用途。
复杂逻辑前 1–2 行中文行注释说明意图/边界。
调试或临时代码标记 TODO: / NOTE:，注明清理条件。

5. 生命周期与职责

Awake：缓存组件、空引用防护、生成默认资源（材质/Mesh）。
Start：外部依赖校验、默认值填充、事件订阅。
Update：输入、动画参数、非物理逻辑。
FixedUpdate：物理、速度/力/碰撞决策。
OnDestroy：解绑事件、销毁自建资源（Mesh/Material/VFX 实例）。
禁止在渲染回调中做逻辑；渲染调试放 OnRenderObject/Gizmos。

6. 序列化与 Inspector

可调参数均序列化并加 [Header]/[Tooltip]/[Range]。
数值在 OnValidate/Awake 用 Mathf.Clamp/Max 做范围保护。
必填引用（Animator/Rigidbody2D/Prefab/LayerMask）启动时检测，缺失 Debug.LogError 并禁用脚本或降级。

7. 输入

所有按键/轴为可配置字段，不在逻辑中硬编码。
输入读取集中在 Update 或输入封装模块；多人/手柄可扩展。

8. 物理与碰撞

2D 刚体默认 CollisionDetectionMode2D.Continuous，冻结无用旋转轴。
多射线/Overlap 检测封装函数；排除自身；LayerMask 必须显式配置，缺失时有回退与警告。
移动/击退/冰冻等通过 Rigidbody/接口（如 SM_IKnockbackable），避免直接改 Transform。
碰撞预测/限速有保护：最大安全速度、预测命中即减速/终止。

9. 战斗与数值

伤害统一入口：Attribute 或 SM_IDamageable.ApplyDamage(SM_DamageInfo)。
记录基础伤害、减伤、最终伤害；元素/暴击集中处理，边界保护（最小 0，最大上限）。
状态效果组件化（Burn/Freeze/Stun/Knockback），支持叠加策略（刷新剩余时间或取最大值，明确约定）。
VFX：prefab + 自动销毁（粒子 duration + 余量或固定超时）；缺失 prefab 只警告不报错。

10. 动画

Animator 参数在启动时 HasParameter 校验并缓存 hash；缺失时警告并回退默认参数名。
Trigger 触发前 ResetTrigger；布尔用于持续态，Trigger 用于瞬态。
动画事件仅做回调，不放重逻辑；状态切换时先清理残留 Trigger。

11. UI

UI 脚本只管显隐与交互；业务逻辑与数据独立。
打开 UI 时处理 Time.timeScale/AudioListener.pause；淡入淡出用 CanvasGroup/Animator，使用 unscaledDeltaTime。
所有 Button/Text/Slider 在 Start 校验空引用；失败时报错并禁用功能。

12. 资源与内存

自建 Mesh/Material/纹理：OnDestroy 释放。
高频对象（投射物/VFX）优先对象池；临时实例必须自动销毁。
禁止在运行时频繁创建 GC 压力大的对象（String.Concat 热路径、LINQ 在核心循环等）。

13. 日志与调试

关键行为（伤害、死亡、冷却、配置缺失、自动回退）保留 Debug.Log/Warning/Error。
量大日志用布尔开关（如 showDebugInfo）；诊断函数用 [ContextMenu] 并标“仅调试”。
Gizmos/Handles 受开关控制；#if UNITY_EDITOR 包裹 Editor 相关 API。

14. 错误处理

空引用防护：早返回 + 日志；外部依赖缺失时禁用脚本或降级。
数值非法（负值/NaN）回退默认并警告。
网络/IO 不在主线程；Unity 主线程操作保持线程安全。

15. 架构与职责

单一职责，小函数；>80 行拆分；公共魔法数抽常量或配置（ScriptableObject）。
跨脚本共享数据用 ScriptableObject/管理器，不用 FindObjectOfType 作为长期方案。
事件订阅成对绑定/解绑；避免匿名委托解绑困难。

16. 提交与目录

不提交 Library/, Logs/, UserSettings/ 等生成目录。
单一变更单一提交；提交前跑对应自测并写明影响范围。
资源命名有前缀（模块_用途），例如：UI_InventoryPanel, VFX_FireHit.

17. 自测清单（新增/修改功能时）

输入：按键/手柄路径可触发；非法输入安全退出。
物理：地面/墙体检测正确，连续碰撞无穿模。
战斗：攻击命中、LayerMask 生效；伤害/元素/暴击日志正确；状态效果叠加符合策略。
UI：可开关，暂停逻辑正确；CanvasGroup 动画无时间缩放问题。
资源：特效/抛射物自动销毁或回收到池；Mesh/Material 释放。
日志：开关可控，缺失配置有清晰错误。

18. 示例代码片段（风格示范）

using UnityEngine;

public class Firebolt : MonoBehaviour
{
    [Header("Config")]
    [SerializeField] private float speed = 8f;
    [SerializeField] private float lifetime = 2.5f;
    [SerializeField] private float damage = 12f;
    [SerializeField] private SM_Element element = SM_Element.Fire;
    [SerializeField] private LayerMask hitLayers;
    [SerializeField] private GameObject hitVfxPrefab;

    private Vector2 direction;
    private float timer;

    public void Launch(Vector2 dir)
    {
        direction = dir.normalized;
    }

    private void Update()
    {
        transform.position += (Vector3)(direction * speed * Time.deltaTime);
        timer += Time.deltaTime;
        if (timer >= lifetime) Destroy(gameObject);
    }

    private void OnTriggerEnter2D(Collider2D other)
    {
        if (((1 << other.gameObject.layer) & hitLayers.value) == 0) return;

        var dmg = other.GetComponent<SM_IDamageable>();
        if (dmg != null)
        {
            dmg.ApplyDamage(new SM_DamageInfo
            {
                Amount = damage,
                Element = element,
                IgnoreDefense = false,
                CritChance = 0.1f,
                CritMultiplier = 1.5f
            });
        }

        PlayHitVfx(other.transform.position);
        Destroy(gameObject);
    }

    private void PlayHitVfx(Vector3 pos)
    {
        if (hitVfxPrefab == null) return;
        var vfx = Instantiate(hitVfxPrefab, pos, Quaternion.identity);
        var main = vfx.GetComponent<ParticleSystem>()?.main;
        Destroy(vfx, main.HasValue && main.Value.duration > 0 ? main.Value.duration + 0.5f : 2f);
    }
}