亚马逊评论无法评论了_如何撰写有效的评论

亚马逊评论无法评论了

One question has come up several times in my career as a software developer:

在我作为软件开发人员的职业生涯中曾多次提出一个问题：

How do you decide when to write a comment? How often should I write comments?

您如何决定何时发表评论？ 我应该多久写一次评论？

It’s a tricky thing to get right. I’ve got some thoughts to share on the matter that I think will help y’all out!

正确是一件棘手的事情。 对于此事，我有一些想法可以分享，我认为这将对您有所帮助！

具名的实体消除了注释的必要 (Well-named entities eliminate the need for comments)

Let’s start with the basics — and a super trivial example at that :). Let’s take a look at a theoretical snippet of production code:

让我们从基础开始-那里是一个简单的例子:)。 让我们看一下生产代码的理论片段：

// Set the title text
titleTextView.text = "Toronto Raptors vs Boston Celtics"// Set the description text
descriptionTextView.text = "Final Score: TOR 104, BOS 100"// Set the background color to grey
containerView.background = COLOR_GREY

Here, because the lines of code are self explanatory, the comments aren’t adding any value. They have simply tripled the number of lines of code without any real benefit. (This would also set an inefficient precedent that other developers might see and follow: typing out tons of unnecessary comments! How much dev time would get wasted by others in this codebase if they followed this example?)

在这里，由于代码行是不言自明的，因此注释不会增加任何值。 他们只是将代码行数增加了三倍而没有任何实际好处。 (这还将为其他开发人员提供一个低效的先例，以供其他开发人员参考：输入大量不必要的注释！如果其他人遵循此示例，那么此代码库中的其他开发人员会浪费多少时间？)

A key question to ask, though, is: why are the comments unnecessary here? They are unnecessary because the names of the views are self-explanatory.

一个关键的问题要问，虽然是：为什么在评论不必要在这里？ 它们是不必要的，因为视图名称是不言自明的。

• titleTextView is clearly the text view that the title should go into.

  titleTextView显然是标题应进入的文本视图。

• descriptionTextView is clearly the text view that the description should go into.

  descriptionTextView显然是描述应包含的文本视图。

So, this is a simple example of the power of good naming: well-named entities eliminate the need for comments.

因此，这是良好命名功能的一个简单示例：名称明确的实体消除了注释的必要。

在整个代码库中建立强大的模式，因此您不必注释大部分 (Establish strong patterns throughout the codebase so you don’t have to comment most of it)

I’m currently working on the Android version of Nike’s Athlete Studio app. My team is all onboard with following Google’s MVVM guidance: utilizing view models, repositories, LiveData, view binding, and all of that jazz.

我目前正在使用Nike的Athlete Studio应用的Android版本。 我的团队全都遵循Google的MVVM指南：利用视图模型，存储库，LiveData，视图绑定以及所有这些爵士乐。

This has resulted in most of our code following a small set of effective patterns. Take, for instance, our Activities. They all follow the same following pattern:

这导致我们的大多数代码遵循一小组有效模式。 以我们的活动为例。 它们都遵循相同的以下模式：

class FooActivity : AppCompatActivity() {
    private lateinit var binding: ActivityFooBinding
    private val fooViewModel: FooViewModel by viewModels {
        FooVMFactory
    }    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivityFooBinding.inflate(layoutInflater)        initializeSecondThingView()        observeFirstThing()
        observeSecondThing()
        ...
    }    private fun observeFirstThing() {
        fooViewModel.firstThing.observe(this) { firstThing ->
            // do whatever it takes to show firstThing in the view
        }
    }    ...
}

The commonality we have across all of our activities includes:

我们所有活动的共同点包括：

• All of them use layout files and their auto-generatedViewBinding instances

  它们都使用布局文件及其自动生成的ViewBinding实例

• All of them use view models that take care of the heavy-lifting of implementing business logic and exposing LiveData objects that the activity needs to trivially connect to the view. (In a lot of cases, we don’t even need to involve the activity to connect the data to the view; we can use data binding to get the layout file to read from the view model directly!)
  它们都使用视图模型，这些模型负责实现业务逻辑的繁重工作，并公开活动需要琐碎地连接到视图的LiveData对象。 (在很多情况下，我们甚至不需要参与将数据连接到视图的活动；我们可以使用数据绑定来获取布局文件以直接从视图模型中读取！)

• All of them follow the same pattern in onCreate of first initializing any view that needs to be initialized (for example, a recycler view would need to have its layout manager set), then observing on view model LiveData objects.

  它们都遵循onCreate的相同模式，首先初始化任何需要初始化的视图(例如，回收者视图将需要设置其布局管理器)，然后观察视图模型LiveData对象。

Because all activities follow this same pattern, there is no need to add comments on these lines of code. Instead, all developers on the project should study and understand the pattern being used, and then utilize it ad infinitum.

因为所有活动都遵循相同的模式，所以无需在这些代码行上添加注释。 相反，项目中的所有开发人员都应研究并了解所使用的模式，然后无限期地使用它。

(Note that this is predicated on having patterns that truly work in solving the problems that need to be solved for the project. The architecture of your project needs to chosen appropriately for this to work.)

(请注意，这是基于具有在解决项目中需要解决的问题时真正起作用的模式。需要适当选择项目的体系结构才能使它起作用。)

It is important for all devs on a project to share the same coding style and naming conventions. If everyone is doing things the same way, there is no opportunity for confusion in the implementation of solutions to commonly encountered problems. (That was a mouthful, I realize!) “Oh, she is just loading up an activity and wiring it up to the view model. Cool, nothing to see here, let’s move on.” This frees time up to be spent on the harder problems in your application.

对于项目中的所有开发人员来说，共享相同的编码样式和命名约定非常重要。 如果每个人都以相同的方式做事，那么在解决常见问题的解决方案的实施中就不会有混乱的机会。 (我知道那是满口的！)“哦，她只是加载一个活动并将其连接到视图模型。 太好了，这里什么也看不到，让我们继续前进。” 这样可以腾出时间花在应用程序中的更难的问题上。

This also makes code reviews so, so much easier. Your senior developers will thank you.

这也使代码审查变得非常容易。 您的高级开发人员将感谢您。

警惕注释代码破坏或避免建立的模式 (Be vigilant about commenting code that breaks or avoids the established patterns)

With the simple stuff handled, it is important that the harder/weirder stuff always contains comments.

通过处理简单的内容，重要的是，较难/更奇怪的内容始终包含注释。

• If you need to break a pattern that is used, it is on you to explain yourself to the devs of the future* why you didn’t do things in the normal way. Were you being a jerk and doing things your own way for the hell of it? Or did you have a good, really hard to see reason to do things differently?

  如果您需要打破一种习惯的模式，那就是要向未来的开发者解释一下自己的原因*为什么您没有以正常的方式做事。 您是个混蛋，还是用自己的方式做事吗？ 还是您有一个很好的，真的很难看出做其他事情的理由的理由？

• If a particular scenario needs to do something very complex and/or unique and/or subtle, comments are going to be helpful to explain what is happening.
  如果特定场景需要做一些非常复杂和/或独特和/或微妙的事情，则注释将有助于解释正在发生的事情。

Ultimately, the goal should be to make sure devs have faith in the quality and honesty of the code. Comments can acknowledge that certain lines of code are weird/not ideal/gross, and that acknowledgement is a very reassuring thing.

最终，目标应该是确保开发人员对代码的质量和诚实性有信心。 注释可以确认某些代码行是奇怪的/不是理想的/粗略的，并且确认是一件非常令人放心的事情。

Note: The “dev of the future”, who is looking for an explanation on why the f*** something was implemented in some bizarre way, is usually yourself 1+ months after you originally wrote the code.

注意：“未来的开发者”正在寻找解释为什么以某种怪异的方式实现f ***的解释，通常是您自己最初编写代码后的一个多月。

结论 (Conclusion)

I hope this gave some insight/perspective on how to write better comments. Feel free to leave any comments on your experiences with.. well, comments. Ciao!

我希望这能对如何撰写更好的评论提供一些见解/观点。 随意对您的体验发表任何评论，也可以发表评论。 再见！

翻译自: https://medium.com/swlh/how-to-write-effective-comments-94ddb00a54b5

亚马逊评论无法评论了