这绝对是主观的,但我想尽量避免它变成争论。我认为如果人们恰当地对待它,这将是一个有趣的问题。
这个问题的想法来自于我对“你最讨厌的语言的哪五件事?”问题的回答。我认为c#中的类在默认情况下应该是密封的——我不会把我的理由放在这个问题上,但我可能会写一个更完整的解释来回答这个问题。我对评论中的讨论热度感到惊讶(目前有25条评论)。
那么,你有什么有争议的观点?我宁愿避免那些基于相对较少的基础而导致相当宗教的事情(例如,大括号放置),但例如可能包括“单元测试实际上并没有多大帮助”或“公共字段确实是可以的”之类的事情。重要的是(至少对我来说)你的观点背后是有理由的。
请提出你的观点和理由——我鼓励人们投票给那些有充分论证和有趣的观点,不管你是否恰好同意这些观点。
对象不应该处于无效状态
不幸的是,许多ORM框架要求所有实体类都使用零参数构造函数,使用setter填充成员变量。在这些情况下,很难知道为了构造一个有效的对象必须调用哪些setter。
MyClass c = new MyClass(); // Object in invalid state. Doesn't have an ID.
c.setId(12345); // Now object is valid.
在我看来,一个对象不可能发现自己处于无效状态,类的API应该在每次方法调用后主动强制它的类不变量。
构造函数和突变方法应该原子地将对象从一种有效状态转换为另一种有效状态。这个好多了:
MyClass c = new MyClass(12345); // Object starts out valid. Stays valid.
作为一些库的使用者,在尝试使用一个对象之前跟踪是否调用了所有正确的setter是一件非常痛苦的事情,因为文档通常没有提供关于类契约的线索。
生成的文档几乎总是毫无价值的。
或者,作为一个推论:您的API需要为维护者和用户提供单独的文档集。
实际上有两类人需要了解您的API:维护者,他们必须了解您的实现的细节,以便有效地完成工作;用户,他们需要高级的概述、示例和关于他们所访问的每个方法的效果的详细细节。
我从未遇到过在这两个方面都成功的生成文档。通常,当程序员为工具编写注释以提取和生成文档时,他们的目标是介于两者之间的某个地方——刚刚足够的实现细节让用户感到厌烦和困惑,但不足以显著帮助维护者,并且没有足够的概述对用户有任何真正的帮助。
As a maintainer, I'd always rather have clean, clear comments, unmuddled by whatever strange markup your auto-doc tool requires, that tell me why you wrote that weird switch statement the way you did, or what bug this seemingly-redundant parameter check fixes, or whatever else I need to know to actually keep the code clean and bug-free as I work on it. I want this information right there in the code, adjacent to the code it's about, so I don't have to hunt down your website to find it in a state that lends itself to being read.
As a user, I'd always rather have a thorough, well-organized document (a set of web pages would be ideal, but I'd settle for a well-structured text file, too) telling me how your API is architectured, what methods do what, and how I can accomplish what I want to use your API to do. I don't want to see internally what classes you wrote to allow me to do work, or files they're in for that matter. And I certainly don't want to have to download your source so I can figure out exactly what's going on behind the curtain. If your documentation were good enough, I wouldn't have to.
无论如何,这就是我的看法。