Isaam Ghanmi | Senior Software Engineer

艾萨姆·甘米| 高级软件工程师

What is a code guide?

什么是代码指南？

Simply put, it is a set of coding conventions that give a uniform appearance to the codes written by different developers.

简而言之，它是一组编码约定，使不同开发人员编写的代码具有统一的外观。

Why do we need it?

我们为什么需要它？

We are often uncertain about the coding style and syntax to use in HTML/CSS. Every developer has his own way to declare the CSS classes, use the right tags, and even formatting the code. Consistent use of style makes it easier for others to understand the code.

我们通常不确定在HTML / CSS中使用的编码样式和语法。 每个开发人员都有自己的方式来声明CSS类，使用正确的标签，甚至格式化代码。 一致地使用样式使其他人更容易理解代码。

At Limehome, we agreed on certain coding rules to create the HTML and CSS.

在Limehome，我们就某些编码规则达成了一致，以创建HTML和CSS。

为什么要定义《代码样式指南》？ (Why should a Code Style Guide be defined?)

Teams should sit together and agree on a style guide. This helps prevent mistakes and confusion when coding. Especially in a fast-growing environment, a style guide can help you scale your business and assist in quick decision making.

团队应该坐在一起，并就风格指南达成一致。 这有助于防止编码时的错误和混乱。 尤其是在快速增长的环境中，样式指南可以帮助您扩展业务并协助快速决策。

Here are some simple steps to follow:

以下是一些简单的步骤：

• Valid HTML must be written. A validator can be used to help you out.

  必须编写有效HTML。 验证程序可以用来帮助您。

• Use lower case element names.使用小写的元素名称。

• Make sure to close empty HTML Elements (e.g. <meta charset="utf-8" />)

  确保关闭空HTML元素(例如<meta charset="utf-8" /> )

• Use elements for what they have been created for. (e.g. use <h> elements for headings and titles, <p> elements for text and paragraphs, <a> elements for anchors, etc.)

  使用元素为其创建内容。 (例如，将<h>元素用于标题和标题，将<p>元素用于文本和段落，将<a>元素用于锚点等)

• Use <picture> tag to support multiple resolutions.

  使用<picture>标签可支持多种分辨率。

• Add alt attribute to images.

  向图像添加alt属性。

• Lazy load the images. It will improve the page loading speed.延迟加载图像。 它将提高页面加载速度。
• Set a fallback for the 404 images. This way viewers won’t jump from your page.为404图像设置后备广告。 这样，观看者就不会跳出您的页面。
• Static assets must be exclusively loaded from a CDN. It boosts the performance.静态资产必须专门从CDN加载。 它提高了性能。

• Images must be exclusively loaded via Imgix

  图片必须通过Imgix专门加载

• Add rel="noopener noreferrer" to external links (for security reasons)

  将rel="noopener noreferrer"添加到外部链接( 出于安全原因 )

• Use label elements to associate text labels with form controls使用标签元素将文本标签与表单控件关联
• Reduce the number of elements on a page as much as you can尽可能减少页面上的元素数量
• All classes and attributes must be in lowercase with hyphens used for separation (don’t use camelCase)所有类和属性都必须使用小写字母，并使用连字符进行分隔(请勿使用camelCase)
• Defer script tags in the head:延迟脚本标签在头部：

Without async or defer: the browser will load the scripts and run it immediately, before rendering the elements that are below the script tag.

没有async或defer ：浏览器将在呈现script标记下方的元素之前加载脚本并立即运行它。

async: the browser will load the HTML and render it while it loads and runs the script at the same time.

异步：浏览器将加载HTML并在加载和运行脚本的同时呈现它。

defer: the browser will run the script after the page finished parsing. (not necessary finishing downloading all image files. This is good.)

延迟：页面解析完成后，浏览器将运行脚本。 (不必完成所有图像文件的下载。这很好。)

以下是一些CSS样式指南的提示： (Here are some of our tips for a CSS Style Guide:)

• Use a reset使用重置
• Set up a Pre-Processor (not worth mentioning but we have to)设置预处理器(不值得一提，但我们必须这样做)

• Always use BEM syntax: http://getbem.com/introduction/

  始终使用BEM语法： http ： //getbem.com/introduction/

• Modern websites are mobile-first: we have only 3 main breakpoints

  现代网站以移动设备为先：我们只有3个主要断点

  -

  --

  768px for portrait tablet layout

  纵向平板电脑布局为768像素

  -

  --

  1024px for landscape layout

  横向布局为1024像素

  -

  --

  1440px for desktop layout

  桌面布局为1440px

• Organize the code with a Top-down Structure用自上而下的结构组织代码

.container {}.header {}.content {}

• Avoid CSS rules nesting.

  避免CSS规则嵌套。

  Why? Because it only makes things worse. Removing it could simplify your code and improve the readability.

  为什么？ 因为这只会使情况变得更糟。 删除它可以简化您的代码并提高可读性。

// Bad.new-page {    background: $silverGray;    .list {        color: $darkGray;    &__item {         color: $lightBlue;     }  }}// Good.new-page {  background: $silverGray;}.list {  color: $darkGray;&__item {    color: $lightBlue;  }}// Better.new-page {  background: $silverGray;}.list {  color: $darkGray;}.list&__item {  color: $lightBlue;}

• No using!important: unless overwriting a style defined in the style attribute(e.g by a js library).

  不使用!important:除非覆盖在style属性中定义的样式(例如，通过js库)。

  No using!important: unless overwriting a style defined in the style attribute(e.g by a js library). Why? Because it messes with the “cascade” of style rules that gives CSS its name. You can easily end up using another !important rule to contribute to a problem caused by using a !important .

  不使用!important:除非覆盖在style属性中定义的样式(例如，通过js库)。 为什么？ 因为它与为CSS命名的样式规则的“层叠”相混淆。 您很容易最终使用另一个!important规则导致使用!important引起的问题。

• Margin and padding: define the complete values(e.g 2px 4px 6px 8px).边距和填充：定义完整的值(例如2px 4px 6px 8px)。

• Define colours in variables. You can use Chir.ag to choose a name for colours. It gives meaningful names.

  在变量中定义颜色。 您可以使用Chir.ag选择颜色的名称。 它给出了有意义的名称。

• Shorthand your CSS简写CSS

// Bad.new-page {  margin-top: 4px;  margin-right: 10px;  margin-bottom: 6px;  margin-left: 8px;}// Good.new-page {  margin: 4px 10px 6px 8px;}

• Use state classes: states are used to style components that are in a special momentary condition like active, disabled or loading. In this case, we don’t follow the BEM guidelines but we add a standalone state class. State classes start with the prefix is- or has- (e.g is-active, has-overlay, is-invisible).

  使用状态类：状态用于设置处于特殊瞬时条件(例如活动，禁用或加载)的组件的样式。 在这种情况下，我们不遵循BEM准则，但添加了一个独立的状态类。 状态类以is-或has-前缀开头(例如is-active ， has-overlay ， is-invisible )。

• Define all CSS properties when overwriting them in media queries:在媒体查询中覆盖所有CSS属性时定义它们：

// Bad.new-page {  margin: 4px 10px 6px 8px;}@media (min-width: 768px) {  margin-top: 24px;}// Good.new-page {  margin: 4px 10px 6px 8px;}@media (min-width: 768px) {  margin: 4px 10px 6px 8px;}

• Classes should explicitly describe their properties but not how they look (e.g width, colour..etc) because that may change.类应该显式地描述其属性，而不是其外观(例如，宽度，颜色等)，因为这可能会改变。

• Comment your code. It can help maintain consistency and facilitate understanding. You can bet whoever is reading your code will thank you for that.

  注释您的代码。 它可以帮助保持一致性并促进理解。 您可以打赌，无论谁正在阅读您的代码，都将对此表示感谢。

  E.g: to explain why

  例如：解释原因

  !important might be needed, to explain a nested code block, to explain why a code block was commented out rather than simply deleted, etc.

  可能需要!important来解释嵌套的代码块，解释为什么要注释掉而不是简单地删除代码块，等等。

• Ask your teammates about the purpose of a non used code before deleting it. It might be used by an external page (e.g CMS)在删除未使用的代码之前，请向您的队友询问其用途。 外部页面(例如CMS)可能会使用它

外卖提示 (Takeaway Tip)

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live! :) Please code for readability.

总是编码，好像最终维护您代码的那个人会是一个暴力的精神病患者，知道您的住所！ :)请编写代码以提高可读性。