注释

好，我们今天学 C# 注释。这是写 Unity 脚本时最基础但很重要的内容。

概念

你先记一句话：

IMPORTANT

注释是写给人看的，不是写给电脑执行的。

电脑编译代码时会忽略普通注释；注释的作用是帮助你、队友、未来的自己理解代码。

一、单行注释 //

单行注释从 // 开始，到这一行结束。

// 角色移动速度
public float speed = 5f;

也可以写在代码后面：

transform.position += Vector3.forward * speed * Time.deltaTime; // 让角色向前移动

在 Unity 里常用于解释一行代码的目的：

void Update()
{
    // 每一帧检测玩家输入
    if (Input.GetKeyDown(KeyCode.Space))
    {
        Jump();
    }
}

适合用在：

• 简单说明变量用途
• 临时屏蔽一行代码
• 提醒自己后面要改
• 标记 TODO

例如：

// TODO: 后面要把跳跃高度改成从配置表读取
public float jumpForce = 8f;

二、多行注释 /\* \*/

多行注释从 /* 开始，到 */ 结束，可以跨很多行。

/*
这是一个玩家控制脚本
负责处理：
1. 移动
2. 跳跃
3. 攻击
*/
public class PlayerController : MonoBehaviour
{
}

也可以临时屏蔽一段代码：

/*
void Attack()
{
    Debug.Log("攻击");
}
*/

但是注意：多行注释不能随便嵌套。

不要这样写：

/*
这里开始注释

/*
里面又写了一个注释
*/

这里可能会出问题
*/

新手最常见的错误就是忘了写结束符 */，导致后面一大段代码都被注释掉，然后 Unity 报一堆奇怪错误。

三、XML 注释 ///

XML 注释是 C# 里比较特殊的一种注释，通常写在类、方法、字段、属性上方。

它不仅给人看，还能被 IDE，比如 Visual Studio、Rider、VS Code，用来显示智能提示。

例子：

/// <summary>
/// 控制玩家移动、跳跃和攻击。
/// </summary>
public class PlayerController : MonoBehaviour
{
}

方法上的 XML 注释：

/// <summary>
/// 让玩家受到伤害。
/// </summary>
/// <param name="damage">本次受到的伤害值。</param>
public void TakeDamage(int damage)
{
    hp -= damage;
}

以后你调用这个方法时，IDE 会提示：

TakeDamage(10);

鼠标放上去，就能看到“让玩家受到伤害”和参数解释。

常见 XML 标签：

/// <summary>
/// 简短说明这个类或方法做什么。
/// </summary>
/// <param name="speed">
/// 参数说明。
/// </param>
/// <returns>
/// 返回值说明。
/// </returns>
/// <remarks>
/// 补充说明，适合写注意事项。
/// </remarks>

完整例子：

/// <summary>
/// 计算玩家最终移动速度。
/// </summary>
/// <param name="baseSpeed">基础速度。</param>
/// <param name="buffRate">加速倍率，例如 1.2 表示增加 20%。</param>
/// <returns>最终移动速度。</returns>
public float CalculateMoveSpeed(float baseSpeed, float buffRate)
{
    return baseSpeed * buffRate;
}

四、三种注释的区别

类型	写法	适合场景
单行注释	//	解释一行代码、TODO、临时屏蔽一行
多行注释	/* */	大段说明、临时屏蔽一段代码
XML 注释	///	给类、方法、属性写正式说明，生成智能提示

五、Unity 里怎么用注释

普通变量可以这样写：

// 玩家当前生命值
public int hp = 100;

但如果你想让 Inspector 里也显示提示，应该用 Unity 的 [Tooltip]：

[Tooltip("玩家移动速度，数值越大移动越快")]
[SerializeField] private float moveSpeed = 5f;

注意区别：

// 这个注释只在代码里能看到
public float speed;
[Tooltip("这个提示会显示在 Unity Inspector 里")]
public float speed;

所以在 Unity 中：

• 给程序员看：用 //、/* */、///
• 给策划、美术、自己在 Inspector 里看：用 [Tooltip]
• 给字段分组：用 [Header]

例子：

public class PlayerController : MonoBehaviour
{
    [Header("移动设置")]
    [Tooltip("玩家每秒移动速度")]
    [SerializeField] private float moveSpeed = 5f;

    [Header("跳跃设置")]
    [Tooltip("玩家跳跃时施加的力量")]
    [SerializeField] private float jumpForce = 8f;

    /// <summary>
    /// 每帧处理玩家输入。
    /// </summary>
    private void Update()
    {
        // 检测移动输入
        Move();

        // 按下空格时跳跃
        if (Input.GetKeyDown(KeyCode.Space))
        {
            Jump();
        }
    }

    /// <summary>
    /// 根据玩家输入移动角色。
    /// </summary>
    private void Move()
    {
        transform.position += Vector3.forward * moveSpeed * Time.deltaTime;
    }

    /// <summary>
    /// 执行跳跃逻辑。
    /// </summary>
    private void Jump()
    {
        Debug.Log("玩家跳跃");
    }
}

六、新手最容易犯的错

不要写废话注释：

// 把 hp 减去 damage
hp -= damage;

这句注释没意义，因为代码本身已经很清楚。

更好的写法是解释“为什么”：

// 护盾已经在服务器结算过，这里只扣最终伤害
hp -= damage;

注释应该解释：

• 这段代码为什么存在
• 有什么特殊规则
• 有什么坑
• 为什么不能随便改
• 和其他系统有什么关系

不要只重复代码本身在做什么。

七、你现在应该怎么练

建一个脚本 PlayerHealth.cs，写下面内容：

using UnityEngine;

/// <summary>
/// 管理玩家生命值。
/// </summary>
public class PlayerHealth : MonoBehaviour
{
    [Tooltip("玩家最大生命值")]
    [SerializeField] private int maxHp = 100;

    // 当前生命值
    private int currentHp;

    private void Start()
    {
        // 游戏开始时，玩家满血
        currentHp = maxHp;
    }

    /// <summary>
    /// 让玩家受到伤害。
    /// </summary>
    /// <param name="damage">受到的伤害值。</param>
    public void TakeDamage(int damage)
    {
        currentHp -= damage;

        if (currentHp <= 0)
        {
            Die();
        }
    }

    /// <summary>
    /// 处理玩家死亡逻辑。
    /// </summary>
    private void Die()
    {
        Debug.Log("玩家死亡");
    }
}

你重点观察三件事：

1. // 是普通代码说明。
2. /// 会给类和方法提供智能提示。
3. [Tooltip] 会在 Unity Inspector 里显示提示。

官方参考

• Microsoft C# XML 文档注释
• Microsoft 推荐 XML 注释标签
• Microsoft XML 注释示例
• Unity 创建和使用脚本