正确评论代码 [英] commenting code properly

问题描述

我一直在寻找一段时间，虽然我不是新编程，但评论标准一直是我从未真正理解过的东西。我知道每个人都会有不同的概念，但一般来说我的问题是：



假设我有一个按钮，并希望在后面的代码中注释click方法。

Ive been searching for some time, and while im not exactly new to programming, commenting standards has always been something i have never really grasped properly. I know everyone will have a difference concept, but in general my question is:

Say i have a button, and wish to comment the click method in the code behind.

/// ************************************************************************
///
/// ************************************************************************
protected void randomButton_Click(object sender, EventArgs e)
{
    // Does something
}

在评论部分，am我的意思是评论方法实际上做了什么，或者实际上它是一个按钮点击事件？



例如。 //在randomButton上触发的方法点击

或

//这个方法做一些随机功能等等等等。



任何建议都会受到赞赏，提前谢谢。

In the comment section, am i meant to be commenting what the method actually does, or that infact it is a button click event?

eg. // Method that fires on randomButton click
or
// This method does some random functionality blah blah.

Any advice would be appreciated, thanks in advance.

推荐答案

不，这不是一个事件。事件是非常不同的。也许，你需要阅读有关事件的内容。最好的情况是，这个方法可以用作事件处理程序，但是很多初学者都被这样一个事实所迷惑：由于某种原因，它并非如此。此外，使用匿名方法可能会好得多;并且你可以从这个匿名方法调用一些语义命名的方法，而不需要你的所有参数，如 sender 和 e 因为它们中的一个或两个通常不用于方法实现。



因此，重点是：在评论方法并解释它的作用之前，正确命名方法，也许，它会大大减少评论的需要。并且 - 上一步 - 在重命名方法之前，你需要编写更好的代码。



回到命名，你的方法名称遭到残酷侵犯（好，我认为）微软命名约定：使用'_'是一种非常糟糕的风格。但更重要的是，如果不应该在按钮名称后面命名：它的名称应该反映它的作用。这就是您对评论的需求可以减少的方式，但阅读评论不是可读性的主要部分。 好的代码是自我评论。



顺便说一句，保留所有这些自动生成的名称是非常糟糕的主意。为什么你认为你被赋予了重构引擎？一旦开始使用它们，您需要重命名所有自动生成的名称。这样的自动生成的名称违反了所有可行的命名和可读性原则：引擎不会知道你的语义，只有你这样做。



所以，你的例子是还没有准备好评论，也许，你还没准备好。在你对如何发表评论发表强烈意见之前，最好不要发表评论。我不是在开玩笑。大多数开发人员实际上过度评论代码您可能会说评论重要的事情很重要。如果你这样说，你将是绝对正确的。问题是：那些不评论真正重要的事情的人和过度评论的人是...... 同一个人。



如何学习评论？不是一个简单的问题。即使是在一篇大文章中，我也不会保证要介绍它：它需要学习如何编写好的干净代码，并分析许多不同的例子。很少有简单的规则和标准无济于事。只有一个建议：阅读你自己的代码。至少你自己的。等到代码完全开发，调试，测试并有点遗忘，然后再读一遍。更好的是，在你看了一年左右之后阅读它。你应该很好地理解你的代码。但很有可能，这将是困难的。试着分析原因。这将是评论的最佳课程。



祝你好运，

-SA

No, this cannot be an event. Event is something very different. Maybe, you need to read about events. At best, this method could be used as an event handler, but so many beginners have been confused by the fact that, by some reason, it is not. Besides, it could be much better to use anonymous method; and you could call some more semantically-named method from this anonymous method, without all of your arguments like sender and e, as one or both of them are often not used in method implementation.

So, the point is: before commenting a method and explaining what it does, name the method properly, maybe, it would highly reduce the need for a comment. And — previous step — before renaming a method, you need to write better code.

Going back to naming, your method name brutally violates (good, I think) Microsoft naming conventions: using '_' is a very bad style. But more importantly, if should not be named after the button name: its name should reflect what it does. This is how your need for comment can be reduced, but reading comments is not a main part of readability. Good code is self-commenting.

By the way, leaving as is all those auto-generated names is extremely bad idea. Why do you think you are given a refactorization engine? You need to rename all auto-generated names as soon as you start using them. Such auto-generated names violate all thinkable naming and readability principles by definition: the engine does no "know" your semantic, only you do.

So, your example is not ready for commenting, and, probably, you are not ready, too. Before you develop strong opinion on how to comment, it's much better not to comment at all. I'm not joking. Most developers actually over-comment code. You may say that it's important to comment something important. If you say so, you will be absolutely right. The thing is: people who don't comment that really important things and people who over-comment are… the same people.

How to learn commenting? Not an easy question. I would not promise to cover it even in a big article: it takes learning how to write good clean code, and analyze many different examples. Few simple rules and "standards" won't help. Just one advice: read your own code. At least your own. Wait until the code is fully developed, debugged, tested and a bit forgotten, and then read again. Better yest, read it after you did not look at it for an year or so. You are supposed to understand your code very well. But chances are, it will be difficult. Try to analyze why. This would be the best lesson of commenting.

Good luck,

—SA

根据Microsoft标准，为所有方法创建摘要。

如果您想遵循评论和编码标准，您可以使用 StyleCop 。



请参阅下面的按钮点击事件示例。

According to Microsoft standards, create summary for all the methods.
If you want to follow comment and coding standards you may use StyleCop.

See below example of button click event.

/// <summary>
/// Method button click event. Get data for the selected method
/// </summary>
/// <param name="sender">
/// object sender.
/// </param>
/// <param name="e">
/// Event arguments
/// </param>
protected void buttonMethod_Click(object sender, EventArgs e)
{
}

这篇关于正确评论代码的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！