Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

h5文档规范（kaowo） #1

Open
Hancoson opened this issue May 5, 2016 · 0 comments
Open

h5文档规范（kaowo） #1

Hancoson opened this issue May 5, 2016 · 0 comments

Comments

@Hancoson
Copy link
Owner

Hancoson commented May 5, 2016

一.目录结构

目录结构

  • App—存放需要引入jQuery的项目；
  • spApp—存放不需要引入jQuery的项目；
  • 特殊情况的项目需要单独新建文件夹，类似share项目；
├── partial                    //脚本
│   └── active-partial         //具体页面          
├── services                   //服务
│   └── services.js     
└── spapp.js                   //路由文件

二.生产环境

H5项目是基于Grunt+bower+AngularJs

Gruntfile.js

- build-ngapp (在dist中生成ngapp项目压缩的代码)
- build-share (在dist中生成share项目压缩的代码)
- build-spapp (在dist中生成spapp项目压缩的代码)
- run-dev (本地未压缩环境服务启动命令)
- run-dist (本地已压缩环境服务启动命令)

三.命名规则

1.项目名

项目名全部采用小写方式， 以中划线分隔。 比如：kaowo-intro

2.HTML文件命名

采用小写方式,多个单词组成时，采用中划线连接方式，比如说: kaowo-intro.html

3.js文件命名

  • 控制器:小写+Ctrl,比如说:procertiCtrl.js
  • 服务:项目简称+Services,比如说:spService.js
  • 路由:项目名称,比如说:spapp.js

4.css文件命名

  • 采用小写方式,多个单词组成时，采用中划线连接方式，比如说: kaowo-intro.css

四.语法规则

1.HTML

语法

  • 使用四个空格的 soft tabs — 这是保证代码在各种环境下显示一致的唯一方式。
  • 嵌套的节点应该缩进（四个空格）。
  • 在属性上，使用双引号，不要使用单引号。
  • 不要在自动闭合标签结尾处使用斜线 - HTML5 规范 指出他们是可选的。
  • 不要忽略可选的关闭标签（例如，
    • 和 ）。

HTML5 doctype

  • 在每个 HTML 页面开头使用这个简单地 doctype 来启用标准模式，使其每个浏览器中尽可能一致的展现。
  • 虽然doctype不区分大小写，但是按照惯例，doctype大写 关于html属性，大写还是小写的一片文章

字符编码

  • 通过声明一个明确的字符编码，让浏览器轻松、快速的确定适合网页内容的渲染方式。
<head>
    <meta charset="UTF-8">
</head>

属性顺序

  • HTML 属性应该按照特定的顺序出现以保证易读性。
id
class
name
data-*
src, for, type, href
title, alt
aria-*, role
  • Classes 是为高可复用组件设计的，理论上他们应处在第一位。Ids 更加具体而且应该尽量少使用（例如, 页内书签），所以他们处在第二位。但为了突出id的重要性， 把id放到了第一位。

减少标签数量

  • 在编写 HTML 代码时，需要尽量避免多余的父节点。很多时候，需要通过迭代和重构来使 HTML 变得更少。 参考下面的示例:
<!-- Not so great -->
<span class="avatar">
    <img src="...">
</span>

<!-- Better -->
<img class="avatar" src="...">

2.css

H5项目中所有的css全部使用less通过grunt编译生成。

语法

  • 使用组合选择器时，保持每个独立的选择器占用一行。
    为了代码的易读性，在每个声明的左括号前增加一个空格。
  • 声明块的右括号应该另起一行。
  • 尽可能使用短的十六进制数值，例如使用 #fff 替代 #ffffff。
  • 为选择器中的属性取值添加引号，例如 input[type="text"]。 他们只在某些情况下可有可无，所以都使用引号可以增加一致性。
  • 不要为 0 指明单位，比如使用 margin: 0; 而不是 margin: 0px;。

声明顺序：

  1. Positioning
  2. Box model 盒模型
  3. Typographic 排版
  4. Visual 外观

Positioning 处在第一位，因为他可以使一个元素脱离正常文本流，并且覆盖盒模型相关的样式。盒模型紧跟其后，因为他决定了一个组件的大小和位置。

*Class 命名 *

  • 保持 Class 命名为全小写，可以使用短划线（不要使用下划线和 camelCase 命名）。短划线应该作为相关类的自然间断。(例如，.btn 和 .btn-danger)。
  • 避免过度使用简写。.btn 可以很好地描述 button，但是 .s 不能代表任何元素。
  • Class 的命名应该尽量短，也要尽量明确。
  • 命名时使用最近的父节点或者父 class 作为前缀。
  • 使用 .js-* classes 来表示行为(相对于样式)，但是不要在 CSS 中包含这些 classes

3.javaScript

完全避免 == != 的使用， 用严格比较条件 === !==

*缩进 分号 空行 *

  • 一律使用4个空格
  • Statement 之后一律以分号结束， 不可以省略
  • 方法之间加
  • 单行或多行注释前加
  • 逻辑块之间加空行增加可读性

*变量 常量 *

  • 标准变量采用驼峰标识
  • 使用的ID的地方一定全大写
  • 使用的URL的地方一定全大写, 比如说 reportURL
  • 构造函数，大写第一个字母
  • 一般情况下统一使用 '' 单引号

*Object Literals *

// Good  semi colon 采用 Followed by space 的形式
var team = {
    title: "AlloyTeam",
    count: 25
};

*Array Literals *

// Good
var colors = [ "red", "green", "blue" ];
var numbers = [ 1, 2, 3, 4 ];

*注释 *

  • 单行注释双斜线后，必须跟注释内容保留一个空格
  • 单行注释可独占一行, 前边不许有空行, 缩进与下一行代码保持一致
  • 可位于一个代码行的末尾，注意这里的格式
  • 多行注释最少三行, 格式如
/*
 * 注释内容与星标前保留一个空格
 */

函数声明

  • 一定先声明再使用， 不要利用 JavaScript engine的hoist特性, 违反了这个规则 JSLint 和 JSHint都会报 warn
  • function declaration 和 function expression 的不同，function expression 的（）前后必须有空格，而function declaration 在有函数名的时候不需要空格， 没有函数名的时候需要空格。
  • 函数调用括号前后不需要空格
  • 立即执行函数的写法, 最外层必须包一层括号
  • "use strict" 决不允许全局使用， 必须放在函数的第一行， 可以用自执行函数包含大的代码段, 如果 "use strict" 在函数外使用， JSLint 和 JSHint 均会报错
function doSomething(item) {
    // do something
}
var doSomething = function (item) {
    // do something
}

// Good
doSomething(item);
// Bad: Looks like a block statement
doSomething (item);

// Good
var value = (function() {
    // function body
    return {
        message: "Hi"
    }
}());

// Good
(function() {
    "use strict";
    function doSomething() {
        // code
    }
    function doSomethingElse() {
        // code
    }
})();
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@Hancoson