风格指南

link 格式约定

学习网站中的文章使用 GitHub Flavored Markdown 撰写，每篇文章开头都包含一些 JSON “前置元数据”（front matter），其中包含文章发布时使用的元数据。

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 散文与语法

  • 在包含三个或更多项目的列表中使用牛津逗号
    • 正确：The load, scroll, and error events (e.g. on an <img> element) do not bubble.
    • 错误：The load, scroll and error events (e.g. on an <img> element) do not bubble.
  • 数字
    • 拼写出小于 10 的数字（例如 one, two, three）
    • 使用数字表示 10 及以上的数字（例如 10, 20, 100）。
  • 缩写
    • 首次引用时拼写出缩写词，并在括号中附上缩写。第二次引用时使用缩写。

link 散文中的代码

  • 始终使用 code 标签来区分代码与散文。
  • 属性：使用点号，后跟属性名称，例如 .length。
  • 函数：使用函数名称，后跟括号，例如 myfunction()。
  • 方法：使用点号，后跟方法名称，后跟括号，例如 The .focus() method is a shortcut for the .bind( "focus", handler ) in the first and second variations, and .trigger( "focus" ) in the third.

link 文章与句子结构

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

link 拼写

  • 使用标准的美国英语拼写。
  • 大写
    • 所有专有名词首字母大写。
    • 代码示例中的 HTML 元素不要首字母大写。
    • 标题或副标题中的所有单词首字母大写，但冠词和介词（如 "with," "of," or "to"）除外。
    • 列表中的第一个单词首字母大写。
  • 标点符号
    • 句号和逗号放在引号内。
    • 避免使用分号。

link 代词用法

  • 不要使用 "I," "me," "us," "our," "we," 以及性别特有的代词如 "him" or "she."
  • 在称呼读者时使用第二人称代词 "you"，在指代代码或内容时使用定冠词 "the"
    • "You will be able to foo bar after you bar the foo."
    • "Insert the paragraph after the unordered list."

link 语气与语调

  • 要使用清晰易懂的陈述句。
  • 要使用主动语态。
  • 写作时要牢记受众。
  • 要使用口语化的方式写作。
  • 要使用第二人称称呼读者。
  • 要使用祈使语气。
  • 要策略性地使用幽默。拿不准时，偏向正式风格。
  • 要使用超链接将读者引导至其他章节已涵盖的概念或主题。
  • 要注明出处。
  • 不要假设读者对主题或概念有先验知识，尤其是在针对初级或中级受众时。
  • 不要使用反问句。
  • 不要使用第一人称或第三人称写作。

link 链接与引用内容

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

link 代码示例

  • 使用示例来说明重要概念。
  • 示例应在代码呈现之前在注释中指出预期结果。
  • 将冗长的示例分解为较短的部分，以帮助理解。
  • 偏好“正确方法”示例而非“错误方法”示例——毕竟，做错事不止一种方式。
  • 使用良好的注释，以便在散文中不需要额外的解释。
  • 提交前测试您的代码示例。
  • 为您的代码示例使用 jQuery 核心代码风格指南。