C#程序的注释标准格式参考

物联网 2025-04-11 18:30
0 阅读

标准注释格式的 C# 程序示例。注释遵循 C# 的 XML 文档注释规范，适用于文件头部、类定义、函数功能等。

文件头部注释

文件头部注释通常包括文件名称、作者、创建日期、版本信息和简要描述。

/// <file>
///     GCodeOptimizer.cs
/// </file>
/// <author>
///     Andrew L. Sandoval
/// </author>
/// <created>
///     2023-10-01
/// </created>
/// <version>
///     1.0.0
/// </version>
/// <summary>
///     This program optimizes G-code files by reducing unnecessary movements and
///     reordering operations to minimize travel time.
/// </summary>

类定义注释

类定义注释包括类的功能描述、作者和版本信息。

/// <summary>
///     Represents a set of G-code operations with a common start and end point.
/// </summary>
/// <remarks>
///     This class is used to group G-code lines that belong to the same operation,
///     such as a cutting path or a drilling sequence.
/// </remarks>
public class GCodeSet
{
    // Class implementation...
}

属性注释

属性注释包括属性的功能描述和可能的取值范围。

/// <summary>
///     Gets or sets the starting X-coordinate of the G-code set.
/// </summary>
/// <value>
///     A double representing the X-coordinate in millimeters.
/// </value>
public double XStart { get; set; }

/// <summary>
///     Gets or sets the ending X-coordinate of the G-code set.
/// </summary>
/// <value>
///     A double representing the X-coordinate in millimeters.
/// </value>
public double XEnd { get; set; }

方法注释

方法注释包括方法的功能描述、参数说明和返回值说明。

/// <summary>
///     Resets the G-code set to its initial state.
/// </summary>
/// <param name="xStart">
///     The starting X-coordinate for the reset operation.
/// </param>
/// <param name="yStart">
///     The starting Y-coordinate for the reset operation.
/// </param>
/// <param name="zStart">
///     The starting Z-coordinate for the reset operation.
/// </param>
/// <remarks>
///     This method clears all lines in the G-code set and sets the start and end
///     coordinates to the specified values.
/// </remarks>
public void Reset(double xStart = 0.0, double yStart = 0.0, double zStart = 0.0)
{
    XStart = xStart;
    YStart = yStart;
    ZStart = zStart;
    XEnd = 0.0;
    YEnd = 0.0;
    ZEnd = 0.0;
    Lines.Clear();
}

构造函数注释

构造函数注释包括构造函数的功能描述和参数说明。

/// <summary>
///     Initializes a new instance of the <see cref="GCodeSet"/> class.
/// </summary>
/// <param name="x">
///     The starting X-coordinate for the G-code set.
/// </param>
/// <param name="y">
///     The starting Y-coordinate for the G-code set.
/// </param>
/// <param name="z">
///     The starting Z-coordinate for the G-code set.
/// </param>
public GCodeSet(double x = 0.0, double y = 0.0, double z = 0.0)
{
    XStart = x;
    YStart = y;
    ZStart = z;
}

枚举注释

枚举注释包括枚举的功能描述和每个枚举值的说明。

/// <summary>
///     Represents the type of G-code operation.
/// </summary>
public enum ShapeType
{
    /// <summary>
    ///     A single point operation.
    /// </summary>
    POINT,

    /// <summary>
    ///     A linear movement operation.
    /// </summary>
    LINE,

    /// <summary>
    ///     A clockwise arc operation.
    /// </summary>
    ARC,

    /// <summary>
    ///     A circular operation.
    /// </summary>
    CIRCLE
}

主程序注释

主程序注释包括程序的功能描述、命令行参数说明和返回值说明。

/// <summary>
///     The main entry point for the G-code optimization program.
/// </summary>
/// <param name="args">
///     Command-line arguments:
///     - inputfile: The path to the input G-code file.
///     - -o outputfile: The path to the output G-code file (optional).
///     - -laser: Enables laser mode (optional).
/// </param>
/// <returns>
///     Returns 0 on success, or a non-zero value on error.
/// </returns>
public static int Main(string[] args)
{
    // Program implementation...
    return 0;
}

完整示例

以下是一个完整的 C# 程序示例，包含标准注释：

/// <file>
///     GCodeOptimizer.cs
/// </file>
/// <author>
///     Andrew L. Sandoval
/// </author>
/// <created>
///     2023-10-01
/// </created>
/// <version>
///     1.0.0
/// </version>
/// <summary>
///     This program optimizes G-code files by reducing unnecessary movements and
///     reordering operations to minimize travel time.
/// </summary>

using System;
using System.Collections.Generic;
using System.IO;

/// <summary>
///     Represents a set of G-code operations with a common start and end point.
/// </summary>
public class GCodeSet
{
    /// <summary>
    ///     Gets or sets the starting X-coordinate of the G-code set.
    /// </summary>
    public double XStart { get; set; }

    /// <summary>
    ///     Gets or sets the starting Y-coordinate of the G-code set.
    /// </summary>
    public double YStart { get; set; }

    /// <summary>
    ///     Gets or sets the starting Z-coordinate of the G-code set.
    /// </summary>
    public double ZStart { get; set; }

    /// <summary>
    ///     Gets or sets the ending X-coordinate of the G-code set.
    /// </summary>
    public double XEnd { get; set; }

    /// <summary>
    ///     Gets or sets the ending Y-coordinate of the G-code set.
    /// </summary>
    public double YEnd { get; set; }

    /// <summary>
    ///     Gets or sets the ending Z-coordinate of the G-code set.
    /// </summary>
    public double ZEnd { get; set; }

    /// <summary>
    ///     Gets or sets the list of G-code lines in the set.
    /// </summary>
    public List<string> Lines { get; set; } = new List<string>();

    /// <summary>
    ///     Initializes a new instance of the <see cref="GCodeSet"/> class.
    /// </summary>
    /// <param name="x">
    ///     The starting X-coordinate for the G-code set.
    /// </param>
    /// <param name="y">
    ///     The starting Y-coordinate for the G-code set.
    /// </param>
    /// <param name="z">
    ///     The starting Z-coordinate for the G-code set.
    /// </param>
    public GCodeSet(double x = 0.0, double y = 0.0, double z = 0.0)
    {
        XStart = x;
        YStart = y;
        ZStart = z;
    }

    /// <summary>
    ///     Resets the G-code set to its initial state.
    /// </summary>
    /// <param name="xStart">
    ///     The starting X-coordinate for the reset operation.
    /// </param>
    /// <param name="yStart">
    ///     The starting Y-coordinate for the reset operation.
    /// </param>
    /// <param name="zStart">
    ///     The starting Z-coordinate for the reset operation.
    /// </param>
    public void Reset(double xStart = 0.0, double yStart = 0.0, double zStart = 0.0)
    {
        XStart = xStart;
        YStart = yStart;
        ZStart = zStart;
        XEnd = 0.0;
        YEnd = 0.0;
        ZEnd = 0.0;
        Lines.Clear();
    }
}

/// <summary>
///     The main entry point for the G-code optimization program.
/// </summary>
public class Program
{
    /// <summary>
    ///     The main entry point for the G-code optimization program.
    /// </summary>
    /// <param name="args">
    ///     Command-line arguments:
    ///     - inputfile: The path to the input G-code file.
    ///     - -o outputfile: The path to the output G-code file (optional).
    ///     - -laser: Enables laser mode (optional).
    /// </param>
    /// <returns>
    ///     Returns 0 on success, or a non-zero value on error.
    /// </returns>
    public static int Main(string[] args)
    {
        // Program implementation...
        return 0;
    }
}

总结

  • 文件头部注释：描述文件的基本信息。

  • 类定义注释：描述类的功能和使用场景。

  • 属性注释：描述属性的作用和取值范围。

  • 方法注释：描述方法的功能、参数和返回值。

  • 枚举注释：描述枚举的功能和每个枚举值的含义。

通过标准注释格式，可以提高代码的可读性和可维护性。

猜你喜欢

目录

热门文章