跳转到： 导航, 搜索

Horizon/Javascript

代码风格

作为一个项目，Horizon 遵循代码质量标准。

JavaScript

以下标准分为必需和推荐部分。我们建立这些最佳实践的主要目标是拥有可靠、可读和可维护的代码。


必需

在提交代码之前，请查看以下检查清单：'可靠'和'可读和可维护'。虽然我们都有自己的偏好，但这些是最常用的指南。

可靠性

  • 代码必须在 Firefox、Chrome、Safari 和 Opera 浏览器的稳定版本和最新版本上工作，以及在 Microsoft Internet Explorer 9 及更高版本上工作。
  • 如果在 local_settings.py 中通过 'COMPRESS_ENABLED = False' 关闭了压缩，请在提交之前重新启用压缩并测试您的代码。
  • 使用 '===' 而不是 '==' 进行相等性检查。'==' 会在比较之前进行类型转换，这可能导致意外结果。注意：如果需要类型转换，建议使用显式转换以保持代码含义清晰。
  • 尽量减少文档重排。DOM 操作代价昂贵，可能成为性能问题。如果您正在访问 DOM，请确保以最优化方式进行。例如，建立一个文档片段，然后一次性将片段附加到 DOM，而不是进行多次较小的 DOM 更新。
  • 使用“严格模式”，将每个 JavaScript 文件包含在自执行函数中。自执行函数将严格模式限定在文件内，因此其变量和方法不会暴露给产品中的其他 JavaScript 文件。注意：使用严格模式将为常见的编码错误（例如访问全局变量）抛出异常，而这些错误通常不会被标记出来。
  Example: 
    (function(){
       'use strict'; 
        // code...
    }) ();
  • 尽可能使用 for each 进行循环。AngularJS 和 jQuery 都提供了 for each 循环，它们提供了迭代和作用域。
  AngularJS:
    angular.forEach(objectToIterateOver, function(value, key) {
        // loop logic
    });

  jQuery:
    $.each(objectToIterateOver, function( key, value ) {
       // loop logic
    });
  • 不要将变量或函数放在全局命名空间中。全局变量有很多缺点，其中之一是包含在应用程序中的所有 JavaScript 都在相同的作用域中运行。这个问题是，如果另一个脚本具有相同的名称，它们会相互覆盖。
  • 始终在变量前面加上 'var'。未在变量前面加上 var 会将该变量放入全局空间，请参见上文。
  • 不要使用 'eval( )'。eval (expression) 会评估传递给它的表达式。这可能会使您的代码面临安全漏洞和其他问题。
  • 不要使用 'with object {code}'。'with' 语句用于访问对象的属性。'with' 的问题在于其执行不一致，因此通过阅读代码中的语句，并不总是清楚它是如何使用的。


可读性与可维护性

  • 为方法和变量赋予有意义的名称
  • 避免过度嵌套.
  • 避免在 JS 代码中使用 HTML 和 CSS。HTML 和 CSS 分别属于模板和样式表。例如
  * In our HTML file, we should focus on layout.

      1. Reduce the small/random '<script>' and '<style>' elements in HTML.
      2. Avoid in-lining styles into element in HTML. Use attributes and classes
         instead

  * In our JS files, we should focus on logic rather than attempting to manipulate
    style elements. 

      1. Avoid statements such as 'element.css({property1,property2...})' they belong in a CSS
         class.
      2. Avoid statements such as '$("<div><span>abc</span></div>")' they belong
         in a HTML template file. Use 'show' | 'hide' | 'clone' elements if dynamic content is required.
      3. Avoid using classes for detection purposes only, instead, defer to
         attributes.

          For example to find a div: 
            <div class="something"></div> 
             $(".something").html("Don't find me this way!");
          
          Is better found like: 
            <div data-something></div> 
             $("div[data-something]").html("You found me correctly!");
  • 避免注释掉的代码.
  • 避免死代码.


推荐

可读性与可维护性

  • 在每个文件的顶部添加注释，解释当命名不明显时该文件的用途。此指南也适用于方法和变量。
  • 源代码格式化（或“美化”）是推荐的，但应谨慎使用。请记住，如果您重新格式化整个先前未以相同方式格式化的文件，它会破坏代码审查期间的差异。最好在您自己处理新文件或与使用相同格式化程序的人一起使用时使用格式化程序。您也可以选择仅格式化文件的选定部分。有关为 Eclipse、Sublime Text、Notepad++ 和 WebStorm/PyCharm 设置 JSHint 的说明，请参阅 此处。
  • 使用 2 个空格进行代码缩进。
  • 对于 'if'、'for'、'while' 语句使用 '{ }'，不要将它们放在同一行上。
// Do this          //Not this          // Not this
if(x) {             if(x)               if(x) y =x;
   y=x;                y=x;                          
}
  • 使用驼峰命名法。“HelloWorld”用于类或对象原型函数，而“helloWorld”用于其他用途（函数声明等）。

AngularJS

“John Papa 风格指南”

John Papa 风格指南是 Angular 代码风格的主要参考点。该风格指南已获得 AngularJS 团队的认可。

风格指南位于以下位置

https://github.com/johnpapa/angular-styleguide

在审查/编写时，请参考此指南的章节。如果遇到问题，请用注释记录下来，并提供指向特定问题的链接。例如，代码应使用命名函数。对此的审查注释应在评论中提供以下链接

https://github.com/johnpapa/angular-styleguide#style-y024

除了 John Papa 之外，以下指南分为必需和推荐部分。

我们还在研究使用 jscs 文件来支持代码风格检查作为门控测试的一部分。

必需

  • 组织：在根 Angular 文件夹（例如 'horizon/static/horizon/js/angular/hz.table.js'）下定义您的 Angular 应用程序。如果您的应用程序足够小，您可以选择将控制器、指令、过滤器等全部放在一个文件中。但是，如果您发现文件正在变得太大并且可读性成为一个问题，请考虑将功能移动到推荐部分中描述的子文件夹中。
  • 分离表示和业务逻辑。控制器用于业务逻辑，指令用于表示。
  1. 控制器和服务不应包含 DOM 引用。指令应该包含。
  2. 服务是单例，包含与视图无关的逻辑
  • 作用域不是模型（模型是您的 JavaScript 对象）。作用域引用模型。表单必须在作用域上的对象属性上运行，而不是直接在 $scope 属性上运行（即，ng-model 必须在点符号上运行）。这同样适用于修改模型数据的其他指令。
  1. 模板中只读，
  2. 控制器中只写
  • 由于 Django 已经使用 '{{ }}'，请使用 '{$ $}' 或 '{% verbatim %}' 代替。
  • 对于 JavaScript 文件中的文本本地化，请使用 'gettext("可翻译文本")' 或 'ngettext("可翻译文本")'。只有这两种方法才被我们的工具识别，并在运行 './run_tests --makemessages' 后包含在 '.po' 文件中。
  • 对于 Horizon 中 AngularJS 模板的本地化，有几种方法可以做到。
  1. 使用从服务器传递到客户端的 'gettext' 或 'ngettext' 函数。如果您只翻译少量内容，可以使用这种方法。
 // Recognized by our tooling                               // Not recognized
 gettext("translatable text");                              var _ = gettext;
 ngettext("translatable text");                             _('translatable text');
 
                                                            $window.gettext('translatable text');
  1. 使用一个 Angular 指令来获取 Django 模板而不是静态 HTML 文件。这里的优势在于，您现在可以使用 '{% trans %}' 以及 Django 提供的任何其他功能。如果您知道内容是静态的，还可以根据区域设置缓存页面。

推荐

  • 使用这些目录：filters、directives、controllers 和 templates。注意：当您使用目录名称时，文件名不必包含“directive”或“filter”等词语。
  • 在控制器文件名末尾加上 "Ctrl"
  • 不要使用位于文件最高级别的变量，例如 "app"，而 Angular 提供了替代方案。例如，使用函数链
 angular.module('_module').controller('_controller', function($scope) {
    // controller code
 }).service('my_service', function($scope) {
   // service code
 });

JSHint

JSHint 是一个很棒的工具，可以在您编辑代码时使用，通过检查您的代码是否符合可配置的检查列表来提高 JavaScript 质量。因此，JavaScript 开发人员应配置他们的编辑器以使用 JSHint，以便提醒他们任何此类错误，以便解决。由于 JSHint 具有大量的配置选项可供选择，因此下面提供了指向 Horizon 希望强制执行的选项的链接，以及有关为 Eclipse、Sublime Text、Notepad++ 和 WebStorm/PyCharm 设置 JSHint 的说明

JSHint 配置文件

.jshintrc

设置 JSHint 的说明

JSHint setup instructions

注意：JSHint 是 Jenkins 执行的自动化单元测试的一部分。自动化测试使用默认配置，这些配置比我们推荐在本地开发环境中运行的配置更不严格。

从 "https://wiki.openstack.org/w/index.php?title=Horizon/Javascript&oldid=81379" 检索