我的前端规范——开篇

大纲

前言
1、规范的重要性
2、关于注释
3、关于文件夹/文件

前言

规范对于一个项目来说是很重要的，统一的规范对代码的一致性、项目的质量、工作的协调都有很大的帮助，而且有时候可以规避很多意料不到的错误。
当然，规范是死的，人是活的。我总结的前端规范是我认为对我来说比较适合的，我又认可的，所以我能比较好的接受和使用。但是，不同的团队，不同的项目需要遵守的规范也许就是不一样的。规范的作用是让项目的代码看起来更有统一性，让团队的协作更方便，因此，根据具体的情况制定统一的规范才是最合理的，而这里我给出的也只是我认为比较符合我风格和习惯的，至于具体的规范还是要依据具体的情况来总结制定。
单独写成一篇的话篇幅很大，因此我会将我的总结写成：开篇、css、html、js四篇，让有需要的读者能够更方便的查找到想要的知识。

1、规范的重要性

说了那么多，也许有些读者还是不以为意的认为规范也只是一些如不是很重要的东西，那么以下一个例子来告诉你，规范有时候起到的作用不仅仅是约束你代码的作用，他还能帮助你规避一些意想不到的bug。

<!--
    这段代码对<p>的首字符样式定义在IE6上看是没有效果的,
    而在p:first-letter和{font-size:300%}加上空格，
    也就是p:first-letter {font-size:300%}后，显示就正常了。 

    这个问题主要是出现在IE6浏览器中，而且这位朋友也说明了一些必要的触发条件： 
        1、IE6浏览器 
        2、选择符是带有伪类的 
        3、伪类中必须是有连接符“-”的，例如:first-letter 
        4、是否有空格的存在
    来源： http://www.cnblogs.com/hustskyking/articles/css-bug-in-IE6.html
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"//www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 
<html xmlns="//www.w3.org/1999/xhtml"> 
<head> 
    <title></title> 
    <style type="text/css"> 
    p{font-size:12px;} 
    p:first-letter{font-size:300%}
    </style> 
</head> 

<body> 
    <p>
      对于世界而言，你是一个人；但是对于某个人，你是他的整个世界。纵然伤心，
      也不要愁眉不展，因为你不知是谁会爱上你的笑容。
    </p> 
</body> 
</html>

2、关于注释

2.1、文件注释

1、文件注释要标明作者、文件版本、创建/修改时间、重大版本修改记录
2、函数描述
3、文件版本、创建或者修改时间、功能、作者
//例子
/**
 * @file Image.js
 * @description 功能详细描述
*/
4、函数或者类等都要添加头描述
//实例
/**
 * 简述
 *
 * 功能详细描述
 *
 * @param <String> arg1 参数1
 * @param <Number> arg2 参数2，默认为0
 * @return <Boolean> 看xxx是否成功
 */
function fooFunction (arg1, arg2) {
}

2.2、操作注释

1、单行注释,写在代码上面
2、多行注释
//例
/*
* 注释操作说明
*/
for( var i = 0; i < obj.lenght; i++) {
}
3、注释标签参考
标签                    描述
@addon                把一个函数标记为另一个函数的扩张，另一个函数的定义不在源文件中。
@argument            用大括号中的自变量类型描述一个自变量。
@author                函数/类作者的姓名。
@base                如果类是继承得来，定义提供的类名称。
@class                用来给一个类提供描述，不能用于构造器的文档中。
@constructor        描述一个类的构造器。
@deprecated            表示函数/类已被忽略。
@exception            描述函数/类产生的一个错误。
@extends            表示派生出当前类的另一个类。
@fileoverview       表示文档块将用于描述当前文件。这个标签应该放在其它任何标签之前。
@final                指出函数/类。
@ignore                让jsdoc忽视随后的代码。
@link                类似于@link标签，用于连接许多其它页面。
@member                定义随后的函数为提供的类名称的一个成员。
@param                用大括号中的参数类型描述一个参数。
@private            表示函数/类为私有，不应包含在生成的文档中。
@requires            表示需要另一个函数/类。
@return                描述一个函数的返回值。
@returns            描述一个函数的返回值。
@see                连接到另一个函数/类。
@throws                描述函数/类可能产生的错误。
@type                指定函数/成员的返回类型。
@version            函数/类的版本号。
来源： http://www.jianshu.com/p/8d291d823cc0

3、关于文件夹/文件

3.1、命名规范

1、文件夹命名：
    英文单词的驼峰法命名
    
2、文件命名：
    全部用小写的英文单词，单词之间用“-”连接。尽量规避数字、拼音以及可能被拦截的单词
命名，如： ad、ads、adv、banner、sponsor、gg、guangg、guanggao。(很多浏览器会将
含有这些词的作为广告拦截： ad、ads、adv、banner、sponsor、gg、guangg、guanggao等
页面中尽量避免采用以上词汇来命名。)

3.2、文件分层

1、文件的分层依据：
           是以业务逻辑为划分基础，在此基础上进行文件的划分
           
    2、这里的分层不一定适用于所有项目，比如有些项目采用了框架(如angular\vue)，那么
这样的项目就不是很适合于这样的分层结构了。
    
root
    -----js（JavaScript脚本

    -----css（样式表

    -----img（图片

    -----swf（flash

    -----src（源文件目录

    -----dep（引入的第三方依赖包目录

    -----font（引入字体目录

我的前端规范——开篇

大纲

前言

1、规范的重要性

2、关于注释

3、关于文件夹/文件

墨念

「多图预警」完美实现一个@功能

在前端使用 JS 进行分类汇总

涨姿势了，有意思的气泡 Loading 效果

你可能不需要JS！CSS实现一个计时器

「彻底弄懂」this全面解析

用了那么久的 SVG，你还没有入门吗？

学会这些 Web API 使你的开发效率翻倍

墨念