这绝对是主观的,但我想尽量避免它变成争论。我认为如果人们恰当地对待它,这将是一个有趣的问题。
这个问题的想法来自于我对“你最讨厌的语言的哪五件事?”问题的回答。我认为c#中的类在默认情况下应该是密封的——我不会把我的理由放在这个问题上,但我可能会写一个更完整的解释来回答这个问题。我对评论中的讨论热度感到惊讶(目前有25条评论)。
那么,你有什么有争议的观点?我宁愿避免那些基于相对较少的基础而导致相当宗教的事情(例如,大括号放置),但例如可能包括“单元测试实际上并没有多大帮助”或“公共字段确实是可以的”之类的事情。重要的是(至少对我来说)你的观点背后是有理由的。
请提出你的观点和理由——我鼓励人们投票给那些有充分论证和有趣的观点,不管你是否恰好同意这些观点。
观点:大多数代码都很糟糕,因为这是程序员想要的。
间接地,我们一直在培育一种极具创造力的文化。这并不是说我不认为解决问题具有创造性元素——它确实存在——只是它与绘画之类的事情根本不一样(参见保罗·格雷厄姆的著名文章《黑客和画家》)。
If we bend our industry towards that approach, ultimately it means letting every programmer go forth and whack out whatever highly creative, crazy stuff they want. Of course, for any sizable project, trying to put together dozens of unrelated, unstructured, unplanned bits into one final coherent bit won't work by definition. That's not a guess, or an estimate, it's the state of the industry that we face today. How many times have you seen sub-bits of functionality in a major program that were completely inconsistent with the rest of the code? It's so common now, it's a wonder anyone cause use any of these messes.
复杂,复杂,丑陋的东西只会变得更糟,更不稳定。如果我们正在建造一些实体的东西,地球上的每个人都会说我们的东西是多么丑陋和糟糕,但由于它或多或少被虚拟隐藏起来,我们能够逃脱一些我们物种所见过的最糟糕的制造过程。(你能想象一辆车有四个不同的人用四种不同的方式设计了四个不同的轮子吗?)
但可悲的是,这一切中有争议的部分是,绝对没有理由这样做,除了历史上的文化倾向于更多的自由和更少的组织,所以我们保持了这种方式(可能变得更糟)。软件开发是一个笑话,但它是一个笑话,因为这是程序员想要的(但永远不会承认这是真的,“管理层的阴谋”对大多数人来说是一个更好的理由)。
我们还会搬起石头砸自己的脚多久,才会幡然醒悟,意识到我们才是握着枪、指着枪、扣动扳机的人?
保罗。
生成的文档几乎总是毫无价值的。
或者,作为一个推论:您的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.
无论如何,这就是我的看法。