您现在的位置: 高手心水论坛 > 高手心水论坛 > 正文
Effective Dart 文档注释在 Flutter 项目中的实践 开发
更新时间:2019-10-08

  在编程语言中,注释就是对代码的解释和说明,其目的是让人们能够更加轻松地了解代码。

  在编程语言中,注释就是对代码的解释和说明,其目的是让人们能够更加轻松地了解代码。

  也有一句话是这样说的:程序员都讨厌两件事,1.别人不写注释 2.自己写注释

  在开发者社区里,我不止一次的看到吐槽离职的前同事不写注释的例子,其实不光是他人的代码,即使是自己写的代码,一段时间以后再去看,你也会发现:这写的什么呀?

  作为开发者,我们大多都知道编写注释的重要性,但是却往往抱着能实现功能就可以了这样的心态去写代码,完全随心所欲的去实现,结果当然就是留下一堆烂摊子,形成前文所述的恶性循环,所以在编写代码的同时,请牢记代码首先是写给人看的。

  编写精炼的、准确的注释 只需要几秒钟,但是以后可能节省其他人几个小时 的时间来读懂您的代码。

  比如,当我们说编程语言时,一定不要省略“编程”这两个字。否则,就可能被误解为大家日常说话用的自然语言。这就是准确性的要求。

  如果代码已经能够清晰、简单地表达自己的语义和逻辑,这时候重复代码语义的注释就是多余的注释。注释的维护是耗费时间和精力的,所以,不要保留多余的、不必要的注释。还有一句很精辟的话:Code tells you How, Comments tell you Why.

  《Effective Dart》中关于如何写注释,也推荐要清晰和准确,同时还有简洁。

  在运用Dart语言编写Flutter应用的过程中,由于视图层都是纯Dart代码,而且夹杂着许多的if..else..,需要根据条件显示不同的widget,因此在做好widget拆分的同时,编写良好的注释势在必行。

  在学习并使用Flutter框架开发App的过程中,有些开发者并没有怎么关注Dart语言,草草看了几下语法之后就开始了Flutter之旅,还是按照以前的Java、Swift这样的语法风格进行开发,这在以后可能会带来不必要的麻烦,比如团队成员里各个都不同的命名方式、注释也各不相同等等。

  因此推荐先看一下《Effective Dart》,主要内容包含代码风格、文档注释、最佳实践、设计指南,能从中获益良多。我们主要关心文档注释这一章节,这里我总结了以下两点:

  由于历史原因,dartdoc 支持两种格式的文档注释:///(“C# 格式”) 和/** ... */(“JavaDoc 格式”)。我们推荐使用///是因为其更加简洁。/**和*/在多行注释中间添加了开头和结尾的两行多余 内容。///在一些情况下也更加易于阅读,例如 当注释文档中包含有使用*标记的列表内容的时候。

  由于历史原因,dartdoc 支持两种格式的文档注释:///(“C# 格式”) 和/** ... */(“JavaDoc 格式”)。我们推荐使用///是因为其更加简洁。/**和*/在多行注释中间添加了开头和结尾的两行多余 内容。///在一些情况下也更加易于阅读,例如 当注释文档中包含有使用*标记的列表内容的时候。

  注释文档中的第一个段落应该是简洁的、面向用户的注释。例如下面的示例, 通常不是一个完成的语句。

  这就跟日常写博客一样,会先写一个段落大意,然后围绕着这点进行详细描述,这样更容易让读者理解核心思想,也更加节省时间。

  在其他语言中,比如JavaDoc使用各种标签和额外的注释来描述参数和 返回值。

  而 Dart 把参数、返回值等描述放到文档注释中,并使用方括号来引用 以及高亮这些参数和返回值。

  项目完成后只简单的在几个关键方法上添加了几个JavaDoc格式的注释,比如:

  相比之前的代码,清晰干净了蛮多,我们在注释的第一行中描述了这个方法的功能,随后以散文的方式对方法的调用、参数以及返回值进行了描述。

  这里方法比较简单,但对于复杂的仓库层的方法,可能包含着网络、数据库、MethodChannel、SharedPreferences等等交互,运用Dart推荐的注释方式,可以更好的描述你的代码逻辑。

  /// 3.通过网络层[_remote] 获取服务端数据,成功后再进行缓存 ,到第4步

  这样,我们轻松的拆解了代码逻辑,也能更容易的编写出相应的测试用例,方便进行单元测试。

  而View层相比Model层和ViewModel层,需要额外注意的是其夹杂着逻辑判断,需要根据条件显示不同的Widget,我们在将复杂部分提取成方法的时候,也需要对其进行详细的描述。

  在运用《Effective Dart》中的注释技巧进行文档注释时,会有一种在写博客的感觉,因为写博客的好处之一便是备忘,将来再复习的时候能够更加快速的理解知识点,注释也是这样。

  我认为即使是再优秀的开发者,如果不写注释,时间长了,也会忘记,而且有幸见识过一个Java文件包含了30000+行代码,还没有注释,到现在都没有人愿意去接手这样的项目,118cc九龙图大家都是程序员,程序员何苦为难程序员呢。

  移动应用 (apps & games) 相关的产品/技术内容。欢迎大家前来分享您对移动应用的行业洞察或见解、移动开发过程中的心得或新发现、以及应用出海的实战经验总结和相关产品的使用反馈等。我们由衷地希望可以给这些出众的中国开发者们提供更好展现自己、充分发挥自己特长的平台。我们将通过大家的技术内容着重选出优秀案例进行谷歌开发技术专家 (GDE) 的推荐。


香港118图库彩图| 香港马会开奖结果直播| 现场报码| 香港跑狗图| 最快开码| 新聚宝盆心水论坛| www.399830.com| 报码图片| 开奖直播现场| 87833.com| www.585kj.com| www.89kj.com|