【代码注释】给脚本加上说明

在开始学习变量和编程概念之前，我们先要掌握一个简单但极其重要的技巧——代码注释。注释就像是给代码加的"便签"或"说明书"，它们不会影响程序的运行，但能让代码更容易理解和维护。

一、 什么是代码注释？

代码注释是程序员在脚本中写的说明文字，计算机会完全忽略这些文字，只执行真正的代码。

注释就像是代码的翻译官：

• 对人类：解释代码的作用和原理

• 对计算机：完全透明，不会被执行

例1：理解注释的基本概念

text

# 这是一行注释，计算机会忽略这行文字
$姓名 = "张三"  # 这是定义学生姓名的变量

二、 为什么要使用注释？

注释能让你的代码变得更友好，就像给地图加上标注一样重要。

没有注释的代码：

text

$n = 45
$s = 87.5
$d = "2024-06-15"

有注释的代码：

text

# 班级学生总数
$学生人数 = 45# 班级平均分数
$平均分 = 87.5# 最近一次考试日期
$考试日期 = "2024-06-15"

三、 注释的基本用法

1. 单行注释
使用 # 符号开头，整行都会被视为注释：

例1：

text

# 这是学生信息管理脚本
# 创建日期：2024年1月
# 作者：张三$学校名称 = "第一中学"  # 设置学校名称变量
$校长姓名 = "李校长"    # 设置校长姓名变量

2. 行尾注释
在代码后面添加注释，说明这行代码的作用：

例2：

text

$温度 = 25        # 当前温度值
$城市 = "北京"     # 所在城市名称
$是否下雨 = $false # 天气状态，false表示不下雨

3. 多行注释
虽然PowerShell没有专门的多行注释语法，但可以每行都用#开头：

例3：

text

# 这个脚本用于管理学生信息
# 功能包括：
# 1. 记录学生基本信息
# 2. 计算成绩统计
# 3. 生成报告文档$版本号 = "1.0"    # 脚本版本信息

四、 注释的最佳实践

好的注释习惯：
例1：

text

# 计算圆的面积
# 参数：半径（单位：厘米）
$半径 = 10                    # 圆的半径
$圆周率 = 3.14159            # 圆周率近似值
$面积 = $圆周率 * $半径 * $半径  # 面积计算公式

需要避免的注释：
例2：

text

$r = 10        # r是10
$p = 3.14159   # p是3.14159
$a = $p*$r*$r  # a等于p乘以r乘以r

注释的黄金法则：

• 解释为什么要这样写代码，而不是是什么

• 在复杂逻辑前加注释

• 为重要的变量添加说明

• 定期更新过时的注释

五、 注释的实际应用

场景1：学习笔记式注释
例1：

text

# ===============================
# 学生信息管理系统 - 学习演示版
# 这是我在学习PowerScript时创建的练习脚本
# 功能：演示变量的基本使用方法
# ===============================# 定义学生基本信息
$学生姓名 = "王小明"    # 学生全名
$学生年龄 = 15         # 学生年龄（整数）
$所在班级 = "九年级二班" # 班级名称# 显示学生信息（练习字符串连接）
"学生姓名：" + $学生姓名
"年龄：" + $学生年龄 + "岁"
"班级：" + $所在班级

场景2：代码功能说明
例1：

text

# 数学计算演示脚本
# 目的：展示基本的数学运算和变量使用# 定义计算所需的变量
$数字A = 30    # 第一个操作数
$数字B = 12    # 第二个操作数# 执行四种基本数学运算
$加法结果 = $数字A + $数字B    # 加法运算
$减法结果 = $数字A - $数字B    # 减法运算
$乘法结果 = $数字A * $数字B    # 乘法运算
$除法结果 = $数字A / $数字B    # 除法运算# 显示所有计算结果
"加法结果：" + $加法结果
"减法结果：" + $减法结果
"乘法结果：" + $乘法结果
"除法结果：" + $除法结果

场景3：调试和测试注释
例1：

text

# 温度转换脚本
# 将摄氏度转换为华氏度$摄氏度 = 25  # 原始温度值（摄氏度）# 转换公式：华氏度 = 摄氏度 × 9/5 + 32
$华氏度 = $摄氏度 * 9 / 5 + 32# 显示转换结果
$摄氏度 + "摄氏度 = " + $华氏度 + "华氏度"# TODO：未来可以添加的功能
# 1. 添加华氏度转摄氏度的功能
# 2. 添加温度范围检查
# 3. 添加图形界面显示

六、 注释的常见用途

1. 脚本头信息
例1：

text

# 脚本名称：学生成绩管理系统
# 版本：v1.0
# 创建时间：2024年1月15日
# 作者：李老师
# 描述：用于记录和统计学生成绩信息
# 最后修改：2024年1月20日

2. 函数或代码块说明
例1：

text

# 计算学生平均成绩
# 输入：成绩数组
# 输出：平均分（保留两位小数）

3. 临时禁用代码
例1：

text

$活跃学生数 = 45
# $转校学生数 = 2  # 暂时不需要这个数据
$总学生数 = $活跃学生数  # 目前只计算活跃学生

七、 注释的最佳实践

1. 保持注释与代码同步

text

# 学生总数（包括转校生）  # 这个注释已经过时
$学生总数 = 45           # 现在只统计活跃学生# 应该更新为：
# 活跃学生总数（不包括转校生）
$活跃学生总数 = 45

2. 使用有意义的注释

text

# 不好的注释：
$x = 10  # 设置x为10# 好的注释：
$最大重试次数 = 10  # 网络请求的最大重试次数

3. 避免过度注释

text

# 不必要的注释（代码本身已经很清晰）：
$姓名 = "张三"  # 将"张三"赋值给姓名变量# 有意义的注释：
$姓名 = "张三"  # 默认测试用户姓名

动手练习

现在请你尝试为下面的代码添加注释：

练习1：为变量添加说明

text

# 请为下面的代码添加合适的注释$产品价格 = 2999
$折扣比例 = 0.8
$运费 = 15
$最终价格 = $产品价格 * $折扣比例 + $运费

练习2：创建完整的脚本头

text

# 请创建一个完整的脚本头注释
# 包括：脚本名称、用途、作者、创建日期等信息$温度 = 25
$城市 = "北京"
"当前" + $城市 + "的温度是：" + $温度 + "摄氏度"

结语

通过本课学习，你已经掌握了代码注释的重要性和使用方法：

• ✅ 注释的基本概念和作用

• ✅ 单行注释和行尾注释的使用

• ✅ 注释的最佳实践和常见用途

• ✅ 如何写出有意义的注释

记住：好的注释就像好的地图标注，能让你和他人更容易理解代码的意图。养成写注释的好习惯，是成为优秀程序员的第一步。

注释不会影响程序的运行，但能极大提高代码的可读性和可维护性。从现在开始，为你写的每一行重要代码都加上清晰的注释吧！