Posted on 2006-11-13 08:49
Cure 阅读(2500)
评论(23) 编辑 收藏 网摘 所属分类:
.Net开发
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文档注释的内容写进去，把不适合写的用其他的文档来代替。