这绝对是主观的，但我想尽量避免它变成争论。我认为如果人们恰当地对待它，这将是一个有趣的问题。
这个问题的想法来自于我对“你最讨厌的语言的哪五件事?”问题的回答。我认为c#中的类在默认情况下应该是密封的——我不会把我的理由放在这个问题上，但我可能会写一个更完整的解释来回答这个问题。我对评论中的讨论热度感到惊讶(目前有25条评论)。
那么，你有什么有争议的观点?我宁愿避免那些基于相对较少的基础而导致相当宗教的事情(例如，大括号放置)，但例如可能包括“单元测试实际上并没有多大帮助”或“公共字段确实是可以的”之类的事情。重要的是(至少对我来说)你的观点背后是有理由的。
请提出你的观点和理由——我鼓励人们投票给那些有充分论证和有趣的观点，不管你是否恰好同意这些观点。
当前回答
生成的文档几乎总是毫无价值的。
或者，作为一个推论:您的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.
无论如何，这就是我的看法。
其他回答
To Be A Good Programmer really requires working in multiple aspects of the field: Application development, Systems (Kernel) work, User Interface Design, Database, and so on. There are certain approaches common to all, and certain approaches that are specific to one aspect of the job. You need to learn how to program Java like a Java coder, not like a C++ coder and vice versa. User Interface design is really hard, and uses a different part of your brain than coding, but implementing that UI in code is yet another skill as well. It is not just that there is no "one" approach to coding, but there is not just one type of coding.
让您的业务逻辑远离DB。或者至少，保持它非常精简。让DB做它应该做的事情。让代码做它应该做的事情。时期。
If you're a one man show (basically, arrogant & egotistical, not listening to the wisdom of others just because you're in control), do as you wish. I don't believe you're that way since you're asking to begin with. But I've met a few when it comes to this subject and felt the need to specify. If you work with DBA's but do your own DB work, keep clearly defined partitions between your business objects, the gateway between them and the DB, and the DB itself. If you work with DBA's and aren't allowed to do your DB work (either by policy or because they're premadonnas), you're very close to being a fool placing your reliance on them to get anything done by putting code-dependant business logic in your DB entities (sprocs, functions, etc.). If you're a DBA, make developers keep their DB entities clean & lean.
不要注释你的代码
注释不是代码，因此当事情发生变化时，不改变解释代码的注释是很容易的。相反，我更喜欢将代码中的垃圾重构到不需要注释的程度。一个例子:
if(data == null) // First time on the page
to:
bool firstTimeOnPage = data == null;
if(firstTimeOnPage)
我唯一一次真正的评论是当它是一个TODO或解释为什么
Widget.GetData(); // only way to grab data, TODO: extract interface or wrapper
调试器是一种拐杖。
它的争议如此之大，以至于连我都不像以前那么相信它了。
缺点:我花了更多的时间来跟上其他人的大量代码，所以任何有助于“我是如何到达这里的”和“发生了什么”的事前或事后分析都是有帮助的。
教授:然而，我很高兴地支持这样的观点，如果你不理解你自己开发的代码或你已经熟悉的代码的这些问题的答案，把所有的时间都花在调试器上并不是解决方案，这是问题的一部分。
在点击“发布你的答案”之前，我快速地检查了一下这个确切的短语，结果发现我不是唯一一个持有这种观点或使用这个短语的人。我在Fog Creek软件论坛上找到了关于这个问题的长时间讨论，其中引用了包括Linus Torvalds在内的各种名人作为著名的支持者。
最好的代码通常不是你写的。作为程序员，我们希望通过编写一些很酷的方法来解决每个问题。任何时候，我们都能在解决问题的同时满足用户80%的需求，而无需引入更多代码进行维护和测试，我们已经提供了更多的价值。
