风格指南

link 格式化约定

学习网站中的文章使用 GitHub 风味 Markdown 编写，每篇文章的开头都包含一些 JSON“前端事项”，其中包含文章发布时使用的元数据。

link 文章标题元数据

每篇文章都应具有以下标题（见下文，因为某些元标记是可选的）

1
2
3
4
5
6
7
8
9
 
<script>{
    "title": <article title>,
    "level": [beginner|intermediate|advance],
    "source": <url of source of the material derived>,
    "attribution": [
        "Ralph Whitbeck <ralph@email.com>",
        "John Paul <john@email.com>"
    ]
}</script>

source 和 attribution 属性是可选的，主要用于从外部来源导入文章，该文章在捐赠给学习网站之前已在外部来源发布。如果您正在撰写新文章或编辑现有文章，则不应包含这些属性。

link 代码块

代码块应以三个反引号开头，不应缩进。（也就是说，该网站更喜欢使用 gfm 支持的“围栏块”符号。）

link 写作风格

内容应具有教育意义，并且对广大开发人员而言易于理解。主要目标受众是初级到中级 jQuery 用户，高级 jQuery 用户为次要受众。在为本网站创建内容时，请牢记以下受众以及以下风格指南

link 散文和语法

  • 在包含三个或更多项目的列表中使用牛津逗号
    • 是：load、scroll 和 error 事件（例如，在 <img> 元素上）不会冒泡。
    • 否：load、scroll 和 error 事件（例如，在 <img> 元素上）不会冒泡。
  • 数字
    • 拼写出 10 以下的数字（例如，一、二、三）
    • 对 10 及以上的数字使用数字（例如，10、20、100）。
  • 缩写
    • 在首次引用时拼出缩写词，然后在括号中加上缩写。在第二次引用时使用缩写。

link 散文中的代码

  • 始终使用 code 标记来表示散文中的代码。
  • 属性：使用点，后跟属性名称，例如 .length。
  • 函数：使用函数名称，后跟括号，例如 myfunction()。
  • 方法：使用点，后跟方法名称，后跟括号，例如 .focus() 方法是第一和第二个变体中 .bind( "focus", handler ) 的快捷方式，在第三个变体中是 .trigger( "focus" )。

链接 文章和句子结构

  • 使用标题将内容分成易于阅读的部分。在文章中以 <h2> 开始标题。
  • 句子要简短，直奔主题。一个好的经验法则是将任何超过 21 个单词的句子分成两个或更多个独立的想法。
  • 列表
    • 在需要时使用项目符号列表来分享一系列五个或更多点。
    • 仅在提供分步说明时使用编号列表——请注意应避免这样做。
    • 在每个有序列表项的末尾使用句点，在无序列表项的末尾使用句点或逗号。

链接 拼写

  • 使用标准的美式英语拼写。
  • 大写
    • 将所有专有名词大写。
    • 不要在代码示例中将 HTML 元素大写。
    • 标题或副标题中的所有单词都大写，但冠词形容词和介词除外，例如“with”、“of”或“to”。
    • 列表中的第一个单词大写。
  • 标点符号
    • 句号和逗号放在引号内。
    • 避免使用分号。

链接 代词用法

  • 不要使用“I”、“me”、“us”、“our”、“we”和性别特定的代词，例如“him”或“she”。
  • 在对读者讲话时使用第二人称代词“you”，在对代码或内容讲话时使用定冠词“the”。
    • “在您对 foo 执行 bar 操作后，您将能够对 foo 执行 bar 操作。”
    • “在无序列表之后插入段落。”

链接 语态和语气

  • 请用清晰易懂的陈述来书写。
  • 请用主动语态来书写。
  • 请在写作时牢记受众。
  • 请用对话式文风写作。
  • 请用第二人称来称呼读者。
  • 请使用命令式语气。
  • 请策略性地使用幽默。如有疑问，请以正式的语气为准。
  • 请使用超链接将读者引至其他部分中已介绍过的概念或主题。
  • 请注明其他人的贡献。
  • 请勿假设读者对主题或概念有先验知识，尤其是在针对初学者或中级受众时。
  • 请勿使用反问句。
  • 请勿用第一人称或第三人称写作。

link 链接和引用内容

  • 在 learn.jquery.com 网站内链接到相关内容，将读者引至之前介绍过的主题或概念。
  • 在必要时链接到 jQuery 博客或 API 文档。
  • 使用内联超链接来引用相关内容。
  • 可接受的外部资源

link 代码示例

  • 使用示例来说明重要概念。
  • 示例应在呈现代码之前在注释中指明预期结果。
  • 将长示例分解为较短的部分，以帮助理解。
  • 优先使用“正确方式”示例，而不是“错误方式”示例——毕竟，错误的方式不止一种。
  • 使用良好的注释，以便无需在散文部分中进行解释。
  • 在提交之前测试你的代码示例。
  • 为你的代码示例使用 jQuery Core 代码样式指南。