不要让注释比代码更难读
2006-11-13 08:49
176 查看
C#的XML 文档注释给我们提供了很多方便,我们可以用它来生成文档,特别是对框架,类库,生成完整的参考手册,还可以在编码时现实提示,帮助。但是,我们也要注意,XML 文档注释有时会给代码的阅读者带来一些不好的体验,我们来看看ZedGraph这个开源项目的一段代码。
下面的这段代码来自ZedGraph的Location.cs文件:
/// <summary>
/// Transform a data point from the specified coordinate type
/// (<see cref="CoordType"/>) to display device coordinates (pixels).
/// </summary>
/// <remarks>
/// If <see paramref="pane"/> is not of type <see cref="GraphPane"/>, then
/// only the <see cref="CoordType.PaneFraction"/> transformation is available.
/// </remarks>
/// <param name="pane">
/// A reference to the <see cref="PaneBase"/> object that contains
/// the <see cref="Axis"/> classes which will be used for the transform.
/// </param>
/// <param name="x">The x coordinate that defines the point in user
/// space.</param>
/// <param name="y">The y coordinate that defines the point in user
/// space.</param>
/// <param name="coord">A <see cref="CoordType"/> type that defines the
/// coordinate system in which the X,Y pair is defined.</param>
/// <returns>A point in display device coordinates that corresponds to the
/// specified user point.</returns>
public static PointF Transform( PaneBase pane, double x, double y, CoordType coord )
{
return pane.TransformCoord( x, y, coord );
}
这个方法的代码总共只有3行,但是注释却有19行,而且这些注释中还夹杂着<see cref="PaneBase"/>和<see paramref="pane"/>这样的引用,使得这段注释看起来比较吃力,如果你好容易把这段注释看完了,展开折叠的代码一看,可能就会有点失望,本来以为有很多代码,结果呢?就一行。
这个函数的参数就4个,不算很多,但是可以相见,当参数增多时,这种注释会更多。所以避免出现过长参数列这种代码的坏味道能够缩短xml文档注释的长度。
函数重载也会对xml文档产生影响。因为在函数重载时常常会调用另一个重载版本,只是再稍加处理,这样就造成函数的多个重载版本的注释有很多是重复的,这同样是一种坏味道。从Location.cs中的其他方法就更可以感受到函数重载对XML文档注释的影响。
C#的文档注释的功能,共有18个标记,如果在注释里过多的使用这些标记,注释本身就会比它要表达的内容更难理解,不但不能起到说明代码的作用,还会加重代码的坏味道。也许这些注释的内容应该在类库参考手册中看,而不是在代码中阅读,但是它确实对代码的阅读者造成了干扰。
要保证注释的清晰易读,仅仅避免代码出现坏味道还是不够的,还要明白,在注释里我们应该写什么而不是能够写什么。把适合写进xml文档注释的内容写进去,把不适合写的用其他的文档来代替。
下面的这段代码来自ZedGraph的Location.cs文件:
/// <summary>
/// Transform a data point from the specified coordinate type
/// (<see cref="CoordType"/>) to display device coordinates (pixels).
/// </summary>
/// <remarks>
/// If <see paramref="pane"/> is not of type <see cref="GraphPane"/>, then
/// only the <see cref="CoordType.PaneFraction"/> transformation is available.
/// </remarks>
/// <param name="pane">
/// A reference to the <see cref="PaneBase"/> object that contains
/// the <see cref="Axis"/> classes which will be used for the transform.
/// </param>
/// <param name="x">The x coordinate that defines the point in user
/// space.</param>
/// <param name="y">The y coordinate that defines the point in user
/// space.</param>
/// <param name="coord">A <see cref="CoordType"/> type that defines the
/// coordinate system in which the X,Y pair is defined.</param>
/// <returns>A point in display device coordinates that corresponds to the
/// specified user point.</returns>
public static PointF Transform( PaneBase pane, double x, double y, CoordType coord )
{
return pane.TransformCoord( x, y, coord );
}
这个方法的代码总共只有3行,但是注释却有19行,而且这些注释中还夹杂着<see cref="PaneBase"/>和<see paramref="pane"/>这样的引用,使得这段注释看起来比较吃力,如果你好容易把这段注释看完了,展开折叠的代码一看,可能就会有点失望,本来以为有很多代码,结果呢?就一行。
这个函数的参数就4个,不算很多,但是可以相见,当参数增多时,这种注释会更多。所以避免出现过长参数列这种代码的坏味道能够缩短xml文档注释的长度。
函数重载也会对xml文档产生影响。因为在函数重载时常常会调用另一个重载版本,只是再稍加处理,这样就造成函数的多个重载版本的注释有很多是重复的,这同样是一种坏味道。从Location.cs中的其他方法就更可以感受到函数重载对XML文档注释的影响。
C#的文档注释的功能,共有18个标记,如果在注释里过多的使用这些标记,注释本身就会比它要表达的内容更难理解,不但不能起到说明代码的作用,还会加重代码的坏味道。也许这些注释的内容应该在类库参考手册中看,而不是在代码中阅读,但是它确实对代码的阅读者造成了干扰。
要保证注释的清晰易读,仅仅避免代码出现坏味道还是不够的,还要明白,在注释里我们应该写什么而不是能够写什么。把适合写进xml文档注释的内容写进去,把不适合写的用其他的文档来代替。
相关文章推荐
- 代码注释中的5要与3不要
- 注释是恶魔,请不要再写一行注释代码
- 代码注释中的5要与3不要
- 代码注释中的5要与3不要
- 代码注释中的5要与3不要
- 代码注释中的5要与3不要
- 代码注释中的5要与3不要
- 编程者必知:代码注释中的5要与3不要
- 编写高质量代码改善C#程序的157个建议——建议152:最少,甚至是不要注释
- 代码注释中的5要与3不要
- 建议编程时不要注释无用代码
- 解决eclipse中java代码注释变成乱码的问题
- titanic版本二代码注释
- 一些VBA基础代码及注释
- dzx2.5 template\default\forum\viewthread_node_body.htm代码调用注释
- Myeclipse学习总结(3)——Myeclipse中的代码格式化、注释模板及保存时自动格式化
- java代码注释翻译
- 编写高质量代码改善C#程序的157个建议——建议119:不要使用自己的加密算法
- 给定一个源代码文件(.cs, .java),输出该文件的总行数、空行数、注释行数、代码行数
- 代码注释要点(Tips to Comment Your Code)