代码书写规范---命名篇

小伙伴们大家好,我是一名菜鸡,但是我现在开始认真记录我的学习心得了,俗话说的好,知其然知其所以然,为什么我要开始记录呢?一方面是因为我的现任师傅(就是管我的)Push我去学习,另一方面是我也想在空闲的时候记录下来自己学到的东西,不至于让我扭头就忘...废话不多说,开始梳理!

一、为什么要规范书写代码?

  • 代码干净整洁
  • 避免重复书写
  • 提高代码质量和可读性
  • 便于团队协作
  • 减少Bug和维护成本
  • 有助于代码复盘和审查
  • ...

二、代码规范从哪几个方面体现?

  • 代码命名规范性
  • 代码注释规范性
  • 提高代码块复用
  • 其他类规范(文件命名规范、文件位置规范)
  • ...

三、不同代码间的规范是否一致?

答案是否定的,但本质上却是相似的。 现在的编程语言有很多种,但你不一定会接触那么多种,那么你在书写一门语言的代码时,就要遵循这一种类代码的编写规范。同样的,现在也有很多框架,你在使用一个框架时,也要遵循这个框架的一些规范,例如代码文件名以及目录命名规范,引入包的书写规范等等...从某些角度出发,程序员所做的事情,在本质上是有映射的,所以很多规范都是形似神不似,所以掌握一种编程语言的具体规范后,再去学习新的语言时,也会自觉的约束书写时的规范!

四、代码规范是全球统一么?

答案也是否定的,很多互联网大厂都有自成一派的代码书写风格,通常会在新员工的入职培训期间内让员工学习并牢记,但是不同厂之间的代码书写风格却不一定一致,但是有一些规定,是代码的创造方在创造这一代码时就提出的希望大家遵守的规范,或者是一些较为权威的协会或者代码维护方提出的规范,我们强调大家学习的是这一类规范,至于每个公司内部具体的规范就需要大家自行去学习,但可以肯定的一点是,所有公司自定的规范都不会和已有的公共性规范相违背。所以:学到就是赚到!


好了,接下来我们先从代码书写规范的命名篇开始讲起:由于我是一名前端er,所以我要首先从前端三剑客的代码书写规范开始讲解,也就是HTML、CSS、JavaScript这三种编程语言,这里我们结合官方给出以及网友总结的一些规范来学习记录!

HTML 篇

在HTML这方面,我们可以参照W3C(万维网联盟)标准,该标准是由万维网联盟方制定和管理的,因此也叫W3C标准,顺带提一下,CSS的规范也是由W3C制定的,不同的编程网站对这些规范进行了一些整理,供大家参考,这里也整理出来结合了菜鸟编程的一份HTML标准:

HTML声明文档类型要放在HTML文档的第一行,也可以使用小写,例如:
xml 复制代码
<!DOCTYPE html>
<!doctype html>
HTML元素名小写,不推荐大写或大小写混合使用
  • 错误示范

    css 复制代码
    <SECTION>  
      <p>这是一个段落。</p>  
    </SECTION>
    <Section>  
      <p>这是一个段落。</p>  
    </SECTION>
  • 正确示范

    css 复制代码
    <section>  
      <p>这是一个段落。</p>    
    </section>
关闭所有HTML元素:虽然有些标签并不需要,但建议给每个元素添加关闭标签
  • 错误示范

    css 复制代码
    <section>  
        <p>这是一个段落。  
        <p>这是一个段落。  
     </section>
  • 正确示范

    css 复制代码
     <section>  
       <p>这是一个段落。</p>    
     </section>
关闭空的HTML元素,在 XHTML 和 XML 中斜线 (/) 是必须的
  • 正确示范

    ini 复制代码
    <meta charset="utf-8" />
属性名小写:尽管允许使用大写字母定义属性名,但小写的属性名便于书写,看起来清爽(官方解释)
  • 错误示范

    ini 复制代码
    <div CLASS="menu">
  • 正确示范

    ini 复制代码
    <div class="menu">
属性值不适用引号,使用引号易于阅读,在属性值含有空格的时候是必须使用引号的,建议统一风格
  • 错误示范

    css 复制代码
    <table class=table striped>
  • 正确示范

    ini 复制代码
    <table class="table striped">
  • 图片的属性建议要使用alt属性,在图片不能显示时能代替图片显示,并定义好尺寸减少加载时的闪烁。

    ini 复制代码
    <img decoding="async" src="html5.gif" alt="HTML5">
    <img src="html5.gif" alt="HTML5" **style=** **"width:128px;height:128px**">
等号前后少用空格,并避免一行代码过长,每行代码应尽量少于80个字符(有争议)
空行和缩进问题:不要无缘无故添加空行,缩进使用4个空格而不是tab,也不是2个空格,较短的代码之间不要使用不必要的空行和缩进
在标准的HTML5中,<html><body><head>标签可以省略,但不建议省略
元数据不可省略,例如:<head>中的<title>
单行注释用<!-- 这是注释 -->, 多行注释用:
xml 复制代码
```
<!--  
  这是一个较长注释。 这是 一个较长注释。这是一个较长注释。  
  这是 一个较长注释 这是一个较长注释。 这是 一个较长注释。  
-->
```

补充版:

  • id 建议单词全字母小写,单词间以 - 分隔。同项目必须保持风格一致。

  • idclass 命名,在避免冲突并描述清楚的前提下尽可能短。

  • 同一页面,应避免使用相同的 nameid

  • 标签使用必须符合标签嵌套规则: 比如 div 不得置于 p 中,tbody 必须置于 table 中。

CSS篇

由于CSS代码较为简单,因此需要注意的点也相对较少:

CSS命名的时候尽量使用一些有意义的单词

不推荐:无意义、与样式相关、中文拼音,例如:

#yee-1901 {} .button-green {} .clear {}

推荐:特殊性、通用性、英文单词,例如:

#gallery {} #login {} .video {} .aux {} .alt {}

推荐:ID或class命名越简短越好,有助于理解和提高代码效率

不推荐:ID和类选择器重名,避免同时使用

命名时的语法规范

一律采用小写+中划线的方式,不允许使用大写字母或者下划线'_'

命名时不允许使用 1 2 3 或者 a b c 等序号类命名

名称中不应该包含颜色或者定位等与具体现实效果相关的信息

  • 常用的命名:
less 复制代码
1-页面结构:

容器: container
页头:header
内容:content/container
页面主体:main
页尾:footer
导航:nav
侧栏:sidebar
栏目:column
页面外围控制整体布局宽度:wrapper
左右中:left right center

2- 导航相关:

导航:nav
主导航:mainbav
子导航:subnav
顶导航:topnav
边导航:sidebar
左导航:leftsidebar
右导航:rightsidebar
菜单:menu
子菜单:submenu
标题: title
摘要: summary

3- 功能类

标志:logo
广告:banner
登陆:login
登录条:loginbar
注册:regsiter
搜索:search
功能区:shop
标题:title
加入:joinus
状态:status
按钮:btn
滚动:scroll
标签页:tab
文章列表:list
提示信息:msg
当前的: current
小技巧:tips
图标: icon
注释:note
指南:guild
服务:service
热点:hot
新闻:news
下载:download
投票:vote
合作伙伴:partner
友情链接:link
版权:copyright

常用class类简写

css 复制代码
- 颜色类,使用颜色名称或者16进制代码
```
.red { color: red; }
.f60 { color: #f60; }
.ff8600 { color: #ff8600; }
```
- 字体大小类,使用"font+字体大小"作为名称
```
.font12px { font-size: 12px; }
.font9pt {font-size: 9pt; }
```
- 对齐样式,使用对齐目标的英文名称
```
.left { float:left; }
.bottom { float:bottom; }
```
- 标题栏样式,使用"类别+功能"的方式命名
```
.barnews { }
.barproduct { }
```
  • CSS属性书写顺序

    • 显示类属性:display/list-style/position/float/clear ...
    • 自身属性(盒模型):width/height/margin/padding/border
    • 背景:background
    • 行高:line-height
    • 文本属性:color/font/text-decoration/text-align/text-indent/vertical-align/white-space/content...
    • 其他:cursor/z-index/zoom/overflow
    • CSS3属性:transform/transition/animation/box-shadow/border-radius
    • 如果使用CSS3的属性,如果有必要加入浏览器前缀,则按照 -webkit- / -moz- / -ms- / -o- / std的顺序进行添加,标准属性写在最后。
  • 其他书写规范

    • 每个声明结束后应该带一个分号
    • margin、padding、border等设置尽量合并,使用短名称
    • 0后面不需要写单位,0.8rpx等应省略为.8rpx

Javascript规范

变量命名规范

ECMAScript 规范中标识符采用驼峰大小写格式,驼峰命名法由小(大)写字母开始,后续每个单词首字母都大写。根据首字母是否大写,分为两种方式:

  • Pascal Case 大驼峰式命名法:首字母大写。eg:StudentInfo、UserInfo、ProductInfo
  • Camel Case 小驼峰式命名法:首字母小写。eg:studentInfo、userInfo、productInfo

JS采用小驼峰式命名法,同时前缀应当是名词(函数的前缀是动词)

同时应当在变量名字中体现所属类型,例如:length、count等表示数字类

常量命名规范

  • 命名全部大写,并用下划线来分割单词,例如:const MAX_COUNT = 10;

函数命名规范

  • 小驼峰式命名,同时前缀应是动词,并参看常用动词规范
    • can :判断某个动作是否可以执行
    • has :判断是否含有某个值
    • is : 判断是否为某个值
    • get :获取某个值
    • set :设置某个值
    • load : 加载某些数据

类&构造函数命名规范

  • 大驼峰式命名,首字母大写,前缀应为名称

  • 类的成员:

    • 公共属性和方法:应当和变量和函数的名称命名保持一致
    • 私有属性和方法:前缀为_(下划线),后面跟公共属性和方法一样的命名方式

注释规范

js 支持三种不同类型的注释:行内注释、单行注释和多行注释:

  • 行内注释和单行注释: 以两个斜线开头,以行位结束

  • 多行注释:以 /* 开头, 以 */ 为结尾,注释文字与 * 之间保持一个空格,若内容较少采用单行的方式,若内容多采用多行注释的方式,开头和结尾各站一行

  • 函数注释:函数注释方法是多行注释的一种,但是包含了特殊的注释要求

    markdown 复制代码
    /**
    *  函数说明
    *  @关键字
    *   */
    • 常用注释关键字:
    less 复制代码
    @param :描述参数的信息
    @return :描述返回值的信息
    @author :描述函数的作者信息
    @version :描述此函数的版本号
    @example :演示函数的使用

其他规范

  • 运算符前后需要加空格

  • 通常使用4个空格符号来缩进代码块

  • 一条语句通常以分号作为结束符

  • 复杂语句的书写规范:

    • 左花括号放在第一行的结尾
    • 左花括号前添加一个空格
    • 将右花括号单独放在一行
    • 一个复杂的声明不要使用分号来结束
  • 对象的定义规则

    • 将左花括号与类名放在同一行。
    • 冒号与属性值间有个空格。
    • 字符串使用双引号,数字不需要。
    • 最后一个属性-值对后面不要添加逗号。
    • 将右花括号独立放在一行,并以分号作为结束符号。
  • 每行代码字符小于80

好了,本篇分享就到这里,后续发现有遗漏会及时补充!

相关推荐
腾讯TNTWeb前端团队32 分钟前
helux v5 发布了,像pinia一样优雅地管理你的react状态吧
前端·javascript·react.js
范文杰4 小时前
AI 时代如何更高效开发前端组件?21st.dev 给了一种答案
前端·ai编程
拉不动的猪4 小时前
刷刷题50(常见的js数据通信与渲染问题)
前端·javascript·面试
拉不动的猪4 小时前
JS多线程Webworks中的几种实战场景演示
前端·javascript·面试
FreeCultureBoy5 小时前
macOS 命令行 原生挂载 webdav 方法
前端
uhakadotcom5 小时前
Astro 框架:快速构建内容驱动型网站的利器
前端·javascript·面试
uhakadotcom6 小时前
了解Nest.js和Next.js:如何选择合适的框架
前端·javascript·面试
uhakadotcom6 小时前
React与Next.js:基础知识及应用场景
前端·面试·github
uhakadotcom6 小时前
Remix 框架:性能与易用性的完美结合
前端·javascript·面试
uhakadotcom6 小时前
Node.js 包管理器:npm vs pnpm
前端·javascript·面试