×

命名规范那些事儿

96
赵萱_dily
2016.06.29 11:09* 字数 3509

开始写代码以来,我们发现最痛苦的不是深奥的算法、不是复杂排版、也不是酷炫的动画,而是最最简单的命名!渐渐发现开发过程中我们60%的时间都花在了给各种各样的东西起名字:

  • 项目名、包名、文件名
  • 项目中引用的图片资源文件名
  • css的类名、id名
  • js方法名、参数变量名
  • 接口名,请求参数名、返回变量名

有时真的会被一波一波的名字攻击的头晕脑胀,索性随便起个名字了事。但这往往却是自己给自己挖坑的开始。这在一个人的小项目中看起来并没有什么影响,但到了大型项目的多人协作和代码维护时,其弊端就开始显现。糟糕的命名往往给代码带来了一堵无形的墙,让我们必须深入代码去研究代码具有的行为,增加了理解代码的时间,也增加了代码维护的难度。

一个正确的命名可以让你更容易地理解代码的程序,好的命名可以消除二义性,消除误解,并且说明真实的意图,甚至可以让你有清新的气息以让你更能吸引异性。--陈皓(左耳朵耗子)

总之,变量名是编程的第一步,第一步走好了,后面才走得好。试想,我们在看一段一目了然的代码时有多么的轻松愉悦~

指导原则

为此我总结了几条关于命名的指导原则,希望能对自己和大家的命名设计带来帮助_

黄金法则- 花一些时间去思考去权衡一下你的变量名
当你设计好一个的变量名一个函数名的时候,别着急去使用他,停下来,想一想,这个变量名是否合适,是否还有更好的?也许你正在使用的是一个很不好的变量名。有些时候,需要我们权衡利弊一下,可能还要去和同事讨论一下。

接下来是一些具体的原则

  1. 语义
    应该让代码“读”起来就像自然语言一样。
  • 变量名应该是名词
    也就是说对于“物理上”的东西,命名其是什么,而不是做什么。比如某些物理上的名字,姓名,性别,文件路径,网络链接,文件描述符,下标索引,类的属性,这些都是物理上的东西,所以,其名字应该是标识其是什么,而不是用来做什么。
  • 函数名应是动词
    也就是说对于“逻辑上”的东西,命名其做什么,而不是是什么。比如某些逻辑上的名字,函数名,数据结构,等。
  1. 准确、精简
    例如:注意区分insert、append并替代add使用。尽可能使用email代替emailAddress,因为后者几乎没有提供比前者更多的信息。不要以任何理由使用临时性的命名

// 反例
temp
button1
button2
a, b, c

  1. 统一
    无论如何,至少在同一个项目中保持统一的命名规范。

  2. 分割标识符中的单词
    不管你用什么命名方式,单词还是要分一下,方便阅读:

JS方法名(驼峰式): someFunction
css类名 : some-class
静态变量: SOME_FUNCTION

具体规范

接下来是我总结的一下具体实用的命名规范,希望和大家一起探讨

项目、包、文件命名

文件名要全部小写, 可以包含下划线 ( _ ) 或连字符 (-). 按项目约定来. 如果并没有项目约定,“ _ ” 更好。

以下是引用** 视觉 **的图片命名规则,视觉和前端er们同时遵守会帮助我们减少很多的工作量,发现合作是如此的愉快~_

关于** 切图命名 **规则:
模块_类别_功能_状态.png
举个栗子: nav_button_search_default.png

名称|命名|名称|命名
:---------------|:---------------|:---------------|:--------------
搜索 |search|按钮|button(btn)
菜单栏|tab |背景 |BG
用户|user|刷新|refresh
图片|image|广告|banner
注册|register|链接|link
导航栏|nav|图标|icon
个人资料|profile|弹出|pop
删除|delete|下载|download
登陆|login|标题|title
注释|note|返回|back
编辑|edit|内容|content
左、右、中|left、right、center|标志|logo
提示信息|msg| |
状态(选中)|selected|状态(不可点)|disabled
状态(默认)|default|状态(按下)|pressed

HTMLSemantic Markup:语义标记

HTML与CSS最佳实践中重要的一条就是怎么来写出有语义可读性的标记。好的语义即是你使用了合适的HTML标签与CSS的类名来传达出你想表达的结构含义。
譬如 h1 标签会告诉我们里面包裹的是一些很重要的标题信息,另一个例子就是*footer *标签,会直截了当地跟你说,这里面是包含一些页脚信息。

写HTML代码时应注意什么?
  1. 尽可能少的使用无语义的标签div和span;
  1. 不要使用纯样式标签,如:b、font、u等,改用css设置。
  2. 需要强调的文本,可以包含在strong或者em标签中(浏览器预设样式,能用CSS指定就不用他们),strong默认样式是加粗(不要用b),em是斜体(不用i);
  3. 使用表格时,标题要用caption,表头用thead,主体部分用tbody包围,尾部用tfoot包围。表头和一般单元格要区分开,表头用th,单元格用td;
  4. 表单域要用fieldset标签包起来,并用legend标签说明表单的用途;
  5. 每个input标签对应的说明文本都需要使用label标签,并且通过为input设置id属性,在lable标签中设置for=someld来让说明文本和相对应的input关联起来。
HTML5新增的语义标签
  1. header元素
    header 元素代表“网页”或“section”的页眉。通常包含h1-h6元素或hgroup,作为整个页面或者一个内容块的标题。也可以包裹一节的目录部分,一个搜索框,一个nav,或者任何相关logo。
    整个页面没有限制header元素的个数,可以拥有多个,可以为每个内容块增加一个header元素如果hgroup或h1-h6自己就能工作的很好,那就不要用header。

<header> <hgroup> <h1>网站标题</h1> <h1>网站副标题</h1> </hgroup> </header>

  1. footer元素
    footer元素代表“网页”或“section”的页脚,通常含有该节的一些基本信息,譬如:作者,相关文档链接,版权资料。如果footer元素包含了整个节,那么它们就代表附录,索引,提拔,许可协议,标签,类别等一些其他类似信息。

<footer> COPYRIGHT@小北</footer>

  1. nav元素
    nav元素代表页面的导航链接区域。用于定义页面的主要导航部分

<nav> <ul> <li>HTML 5</li> <li>CSS3</li> <li>JavaScript</li> </ul> </nav>

  1. aside元素
    aside元素被包含在article元素中作为主要内容的附属信息部分,其中的内容可以是与当前文章有关的相关资料、标签、名次解释等。(特殊的section)
    在article元素之外使用作为页面或站点全局的附属信息部分。最典型的是侧边栏,其中的内容可以是日志串连,其他组的导航,甚至广告,这些内容相关的页面。

<article> <p>内容</p> <aside> <h1>作者简介</h1> <p>萱萱,前端一枚</p> </aside> </article>

  1. section元素
    section元素代表文档中的“节”或“段”,“段”可以是指一篇文章里按照主题的分段;“节”可以是指一个页面里的分组。
    section通常还带标题,虽然html5中section会自动给标题h1-h6降级,但是最好手动给他们降级。如下:

<section> <h1>section是啥?</h1> <article> <h2>关于section</h1> <p>section的介绍</p> <section> <h3>关于其他</h3> <p>关于其他section的介绍</p> </section> </article> </section>

article、nav、aside可以理解为特殊的section,所以如果可以用article、nav、aside就不要用section,没实际意义的就用div

  1. article元素
    article元素最容易跟section和div容易混淆,其实article代表一个在文档,页面或者网站中自成一体的内容,其目的是为了让开发者独立开发或重用。譬如论坛的帖子,博客上的文章,一篇用户的评论,一个互动的widget小工具。(特殊的section)
    除了它的内容,article会有一个标题(通常会在header里),会有一个footer页脚。

<article> <h1>一篇文章</h1> <p>文章内容..</p> <footer> <p><small>版权:html5jscss网所属,作者:小北</small></p> </footer> </article>

article使用注意:

  • 自身独立的情况下:用article
  • 是相关内容:用section
  • 没有语义的:用div

css命名

接下来是css中成“吨”的class的命名

命名规则
  1. class 名称中只能出现小写字符和破折号(dashe)(不是下划线,也不是驼峰命名法)。破折号应当用于相关 class 的命名(类似于命名空间)(例如,.btn和 .btn-danger)。
  2. 首字符必须是字母,禁止数字或其他特殊字符。
  3. 避免过度任意的简写。.btn代表 button,但是 .s不能表达任何意思。
  4. 使用有意义的名称。使用有组织的或目的明确的名称,不要使用表现形式(presentational)的名称。避免使用123456…, red, blue, left, right之类的(如颜色、字号大小等)矢量命名,如class="left-news"、class="2",以避免当状态改变时名称失去意义。尽量用单个单词简单描述class名称。
  5. 基于最近的父 class 或基本(base) class 作为新 class 的前缀。
  6. 双单词或多单词组合方式:形容词-名词、命名空间-名次、命名空间-形容词-名词。例如:news-list、mod-feeds、mod-my-feeds、cell-title
Class 和 id的使用方法

把id留给后台开发和JS使用,除此之外页面的page id(如首页的外层需要一个ID id="pageIndex"),页面结构(header main footer)允许用id命名(ID命名建议使用驼峰命名)。其他禁止id使用在样式表CSS命名中,一律使用class命名。

CSS内部的分类及其顺序
  1. 重置(reset)和默认(base)(tags):消除默认样式和浏览器差异,并设置部分标签的初始样式,以减少后面的重复劳动,可以根据你的网站需求设置.
  2. 统一处理:建议在这个位置统一调用背景图(这里指多个布局或模块或元件共用的图)和清除浮动(这里指通用性较高的布局、模块、元件内的清除)等统一设置处理的样式!
  3. 布局(grid)(.grid-):将页面分割为几个大块,通常有头部、主体、主栏、侧栏、尾部等!
  4. 模块(module)(.mod-):通常是一个语义化的可以重复使用的较大的整体!比如导航、登录、注册、各种列表、评论、搜索等!
  5. 元件(unit)(.u-):通常是一个不可再分的较为小巧的个体,通常被重复用于各种模块中!比如按钮、输入框、loading、图标等!
  6. 功能(function)(.fun-):为方便一些常用样式的使用,我们将这些使用率较高的样式剥离出来,按需使用,通常这些选择器具有固定样式表现,比如清除浮动等!不可滥用!
  7. 皮肤(skin)(.skin-):如果你需要把皮肤型的样式抽离出来,通常为文字色、背景色(图)、边框色等,非换肤型网站通常只提取文字色!非换肤型网站不可滥用此类!
  8. 状态:为状态类样式加入前缀,统一标识,方便识别,她只能组合使用或作为后代出现
推荐通用命名
  1. 页面框架命名,一般具有唯一性
ID名称 命名 ID名称 命名
头部 header 主体 main
脚部 footer 容器 wrapper
侧栏 sideBar 栏目 column
布局 layout

2.模块结构命名

Class名称|命名|Class名称|命名
:---------------|:---------------|:---------------|:-- -------------
模块(如:新闻模块) |mod (mod-news) |标题栏 |title
内容 |content |次级内容 |sub-content

3.导航结构命名

Class名称 命名 Class名称 命名
导航 nav 主导航 main-nav
子导航 sub-nav 顶部导航 top-nav
菜单 menu 子菜单 sub-menu

4.一般元素命名

Class名称 命名 Class名称 命名
二级 sub 面包屑 breadcrumb
标志 logo 广告 banner
登陆 login 注册 register/reg
搜索 search 加入 join
状态 status 按钮 btn
滚动 scroll 标签页 tab
文章列表 list 短消息 msg/message
当前的 current 提示小技巧 tips
图标 icon 注释 note
指南 guide 服务 service
热点 hot 新闻 news
下载 download 投票 vote
合作伙伴 partner 友情链接 link
版权 copyright 演示 demo
下拉框 select 摘要 summary
翻页 pages 主题风格 themes
设置 set 成功 suc
按钮 btn 文本 txt
颜色 color/c 背景 bg
边框 border/bor 居中 center
top/t bottom/b
left/l right/r
添加 add 删除 del
间隔 sp 段落 p
弹出层 pop 公共 global/gb
操作 op 密码 pwd
透明 tran 信息 info
重点 hit 预览 pvw
单行输入框 input 首页 index
日志 blog 相册 photo
留言板 guestbook 用户 user
确认 confirm 取消 cancel
报错 error

5.全局皮肤样式

  • 文字颜色(命名空间text-xxx)
    text-c1, text-c2,text-c3……

  • 背景颜色(命名空间bg -xxx)
    bg-c1,bg-c2,bg-c3……

  • 边框颜色(命名空间border-xxx)
    border-c1,border-c2,border-c3……

JS命名(驼峰式)

JS的变量和方法命名除了遵循上文的指导原则外最重要的是采用驼峰式命名,保证见文知义。

随笔
Web note ad 1