悟夕导航
悟夕导航/编程知识/正文

把代码写成诗：一份可执行的 HTML5 风格手册

119 0 0

好代码像排版精良的书——扫一眼就知道哪里是标题，哪里是脚注。HTML 不是“能跑就行”的草稿，而是给浏览器、同事以及三个月后的自己看的公共文本。下面这份“风格手册”可直接塞进团队 Wiki，也能当个人 checklist，每天 save 之前勾一遍。

1. 起手式：样板文件

新建 .html 时，一次性把骨架敲到位，避免漏写 lang、viewport 而返工。

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>页面标题 | 站点名</title>
  <link rel="stylesheet" href="css/main.css">
</head>
<body>
  <!-- 内容 -->
</body>
</html>
  • 用 zh-CN 而不是 zh，让读屏软件发音更准确。
  • 省掉 type="text/css" 之类过时属性，HTML5 约定俗成。

2. 缩进：两个空格，无 Tab

<section>
  <h2>章节标题</h2>
  <p>段落。</p>
</section>

理由：

  1. 4 空格在窄屏笔记本上很快折行；2. Tab 在不同编辑器宽度不可控。
    一键设置：VS Code → 右下角 “Spaces: 2”。

3. 命名：小写 + 连字符

<header class="site-header">
  <nav class="main-nav" id="nav-primary"></nav>
</header>
  • 拒绝驼峰：CSS 里也是连字符，保持一致。
  • 拒绝缩写：.btn 可以，.s-h 不行，后者打断了阅读节奏。

4. 语义优先：能少一个 <div> 就少一个

<!-- 不好 -->
<div class="article">
  <div class="article-header"><h2>标题</h2></div>
  <div class="article-body"><p>正文</p></div>
</div>

<!-- 好 -->
<article>
  <header><h2>标题</h2></header>
  <p>正文</p>
</article>

搜索引擎、读屏器、后期维护者同时受益。

5. 属性顺序：把“全局身份证”放最前

推荐顺序：
id > class > src > type > name > value > data-* > aria-* > 其余

<input id="email" class="form-input" type="email" name="email" required>

团队扫代码时，先瞄一眼就能定位 JS 钩子（id）和样式钩子（class）。

6. 引号风格：双引号一统江湖

<img src="cat.png" alt="一只喵">

单引号与 JS 字符串嵌套易混淆；双引号与 JSON 风格一致。

7. 注释：写“为什么”，而不是“是什么”

<!-- 导航：平滑滚动目标由 JS 监听 -->
<nav class="toc">
  <a href="#intro">简介</a>
</nav>

避免废话：
<!-- 链接 --> → 任何人都能看出这是链接，无需注释。

8. 分离主义：行内样式 = 技术债

<!-- 一次性邮件模板除外 -->
<p style="color:red;">紧急</p>

紧急也给我写进 .urgent { color: red; }，然后加 class。
好处：后期换主题色只改一行 CSS。

9. 自动化校验：把错误消灭在保存瞬间

  • 安装 VS Code 插件：HTMLHint + W3C Validator
  • 保存即提示：未闭合标签、重复 id、非法嵌套一目了然。
  • CI 阶段加 npm run html-validate，合并请求不通过测试不许进主分支。

10. 文件切分：按“区块”而非“类型”组织

/scss
  ├─ component/_button.scss
  ├─ layout/_header.scss
/html
  ├─ index.html
  ├─ _header.html   <!-- 统一 include -->
/js
  ├─ module/_nav.js

用 gulp/webpack 把 _header.html 注入各页，保证导航一改全站生效。

11. 最后 30 秒 checklist

保存前按一遍：

  • [ ] 缩进 2 空格
  • [ ] 标签语义化
  • [ ] 属性双引号 + 顺序
  • [ ] 无行内样式
  • [ ] 注释写“为什么”
  • [ ] 通过 HTMLHint 0 错误

把代码当产品，把风格当品牌。
当团队每个人都写出“长得一样”的 HTML， review 时就能把注意力放在业务逻辑，而不是争论括号到底换不换行。愿你也能把“诗”写在每一对标签之间。

0
快来点个赞吧

发表评论

隐私评论

评论列表

来写一个评论吧