目錄

?一、命名規范

1.1 項目文件命名

1.2 Vue 組件命名

1.3 代碼參數命名

二、代碼規范

2.1 Vue? 主要針對vue2.x

2.2 HTML

2.3 CSS

2.4 JavaScript

三、注釋規范

3.1 HTML 文件注釋

3.2 CSS 文件注釋

3.3 JavaScript 文件注釋

四、其它

?五、GIS規范?

GIS亮點

六、移動端app、小程序規范

---

?一、命名規范

市面上常用的命名規范：

• camelCase（小駝峰式命名法 —— 首字母小寫）

• PascalCase（大駝峰式命名法 —— 首字母大寫）

• kebab-case（短橫線連接式）

• Snake（下劃線連接式）?

1.1 項目文件命名

1.1.1 項目名

全部采用小寫方式， 以短橫線分隔。例：whclould-smart-port / my-project-name。

1.1.2 目錄名

參照項目命名規則，有復數結構時，要采用復數命名法。例：assets、components、directives、mixins、utils、views。

whclould-smart-port / my-project-name |- node_modules // 下載的依賴包 |- public // 靜態頁面目錄|- js // 其他靜態資源文件 例如：imosSdk.min.js|- html // 其他靜態資源文件 例如：imosSdk.html|- favicon.ico // 網站圖標|- index.html // 項目入口 |- src // 源碼目錄|- api // http 請求目錄|- assets // 靜態資源目錄，這里的資源會被wabpack構建|- icon // icon 存放目錄|- img // 圖片存放目錄|- js // 公共 js 文件目錄|- scss // 公共樣式 scss 存放目錄|- frame.scss // 入口文件|- global.scss // 公共樣式|- reset.scss // 重置樣式|- styles // UI框架覆蓋主題 文件夾|- components // 組件|- plugins // 插件|- router // 路由|- routes // 詳細的路由拆分目錄（可選）|- index.js|- store // 全局狀態管理|- utils // 工具存放目錄|- request.js // 公共請求工具|- variable.js // 公共請求地址、參數配置文件|- util.js // 公共方法類|- views // 頁面存放目錄|- App.vue // 根組件|- main.js // 入口文件|- tests // 測試用例|- .browserslistrc// 瀏覽器兼容配置文件|- .editorconfig // 編輯器配置文件|- .eslintignore // eslint 忽略規則|- .eslintrc.js // eslint 規則|- .gitignore // git 忽略規則|- babel.config.js // babel 規則|- package-lock.json|- package.json // 依賴|- README.md // 項目 README|- vue.config.js // webpack 配置

1.1.3 圖像文件名

全部采用小寫方式， 優先選擇單個單詞命名，多個單詞命名以下劃線分隔。

圖片文件夾命名：

單個單詞文件小寫命名，例如：home ??

多個單詞文件命名： camelCase?小駝峰式命名法，例如：視頻組件用：monitorVideo

圖像文件命名：

banner_first.gif menu_collpase.gif menutitle_news.gif logo_police.gif logo_national.gif pic_people.jpg pic_TV.jpg

1.1.4 HTML 文件名

全部采用?小寫方式， 優先選擇單個單詞命名，多個單詞命名以camelCase小駝峰式命名法分隔。

|-?errorPage.html |-?successPage.html |-?h5Port.html

1.1.5 CSS 文件名

全部采用小寫方式， 優先選擇單個單詞命名，多個單詞命名以短橫線分隔。

|-?normalize.less |-?base.less |-?date-picker.scss |-?input-number.scss

1.1.6 JavaScript 文件名

全部采用小寫方式， 優先選擇單個單詞命名，多個單詞命名以短橫線分隔。

|-?index.js |-?plugin.js |-?util.js |-?date-util.js |-?account-model.js |-?collapse-transition.js

1.2 Vue 組件命名

1.2.1 單文件組件名

文件擴展名為?.vue?的?single-file components?(單文件組件)。單文件組件名應該始終是單詞大寫開頭?(PascalCase)，大駝峰式命名法。

components/ |- MyComponent.vue

1.2.2 單例組件名

每個頁面只使用一次，甚至單個項目只使用一次，比如，菜單欄，頭部，側邊欄等

以The?前綴命名，以示其唯一性

components/|- ThePublic|- TheHeading.vue|- TheSidebar.vue

1.2.3 基礎組件名

基礎組件：不包含業務，獨立、具體功能的基礎組件，比如日期選擇器、模態框等。這類組件作為項目的基礎控件，會被大量使用，因此組件的 API 進行過高強度的抽象，可以通過不同配置實現不同的功能。

展示類的、無邏輯的或無狀態、不摻雜業務邏輯的組件) 應該全部以一個特定的前綴開頭 —— Base。基礎組件在一個頁面內可使用多次，在不同頁面內也可復用，是高可復用組件。

例如：漁港項目中日期選擇組件：BaseDatePicker.vue

components/ |- BaseButton.vue |- BaseTable.vue |- BaseIcon.vue |- BaseDatePicker.vue

1.2.4 業務組件

業務組件：它不像基礎組件只包含某個功能，而是在業務中被多個頁面復用的（具有可復用性），它與基礎組件的區別是，業務組件只在當前項目中會用到，不具有通用性，而且會包含一些業務，比如數據請求；

摻雜了復雜業務的組件（擁有自身?data、prop?的相關處理）即業務組件應該以?Custom?前綴命名。業務組件在一個頁面內比如：某個頁面內有一個卡片列表，而樣式和邏輯跟業務緊密相關的卡片就是業務組件。

例如：智慧漁港項目中矩陣拖拽組件

components/ |- CustomCard.vue |- CustomMatrixDrag.vue |- CustomMonitor.vue

1.2.5 緊密耦合的組件名

父子組件緊密耦合性組件以父組件名為前綴，因為編輯器通常會按字母順序組織文件，所以這樣做可以把相關聯的文件排在一起。

components/ |- VideoList.vue |- VideoListItem.vue |- VideoListItemPlayer.vue

1.2.6 組件名中單詞順序

組件名應該以高級別的 (通常是一般化描述的) 單詞開頭，以描述性的修飾詞結尾。?因為編輯器通常會按字母順序組織文件，所以現在組件之間的重要關系一目了然。如下組件主要是用于搜索和設置功能。

components/ |- SearchContent.vue |- SearchIcon.vue |- SearchRunButton.vue

組件名盡量以完整單詞命名，單詞盡量語義化，方便閱讀。

1.3 代碼參數命名

1.3.1 name

組件名應該始終是多個單詞，應該始終是 PascalCase 的。?根組件 App 以及?<transition>、<component>?之類的 Vue 內置組件除外。這樣做可以避免跟現有的以及未來的 HTML 元素相沖突，因為所有的 HTML 元素名稱都是單個單詞的，而且避免與自定義變量沖突，帶來不必要的麻煩。

export default {name: 'ToDoList',// ... }

1.3.2 prop

在聲明 prop 的時候，其命名應該始終使用 camelCase，而在模板和 JSX 中應該始終使用 kebab-case。我們單純的遵循每個語言的約定，在 JavaScript 中更自然的是 camelCase。而在 HTML 中則是 kebab-case。

export default {name: 'MyComponent',// ...props: {videoNumber: {type: Number,required: true,validator: function (value) {return value>0}}} }

1.3.3 router

Vue Router Path 命名采用 kebab-case 格式?；蛘?span style="color:#1a439c;">PascalCase大駝峰命名，推薦使用kebab-case 短橫線。

?用 Snake（如：/user_info）或 camelCase（如：/userInfo)的單詞會被當成一個單詞，搜索引擎無法區分語義

// bad {path: '/user_info', // user_info 當成一個單詞name: 'UserInfo',component: UserInfo,meta: {title: ' - 用戶',desc: ''} }, // not bad{path: '/UserInfo',name: 'UserInfo',component: UserInfo,meta: {title: ' - 用戶',desc: ''} },// better {path: '/user-info', // 能解析成 user infoname: 'UserInfo',component: UserInfo,meta: {title: ' - 用戶',desc: ''} },

1.3.4 模板中組件

對于絕大多數項目來說，在單文件組件和字符串模板中組件名應該總是 PascalCase 的，但是在 DOM 模板中總是 kebab-case 的。

<!-- 在 DOM 模板中 --> <ys-video></ys-video>export default {components: {YsVideo}, }

1.3.5?變量

• 命名方法：camelCase

• 命名規范：類型 + 對象描述或屬性的方式

// bad var getSsss = "LoginTable" var aa = "123" var b1 = 0 var b2 = 1// good let tableTitle = "視頻列表" let mySchool = "我的學校" let ysVideoList = [...] //宇視視頻列表

1.3.6?常量

• 命名方法：全部大寫下劃線分割

• 命名規范：使用大寫字母和下劃線來組合命名，下劃線用以分割單詞

const MAX_COUNT = 10 const URL = 'http://xxx.xxxx.com' const COOKIE_EXPIRES = 30

1.3.7?方法

• 命名方法：camelCase

• 命名規范：統一使用動詞或者動詞 + 名詞形式

//?1、普通情況下，使用動詞?+?名詞形式jumpPage、openCarInfoDialog、loginIn、loginOut、openDialog//?2、請求數據方法，以?Api?結尾getListApi、postFormApi、getUserInfoApi//?3、單個動詞的情況 init、refresh、load

1.3.8?自定義事件

自定義事件應始終使用 kebab-case 的事件名。

官方建議：

不同于組件和 prop，事件名不存在任何自動化的大小寫轉換。而是觸發的事件名需要完全匹配監聽這個事件所用的名稱。

this.$emit('my-event') <MyComponent?@my-event="handleDoSomething"?/>

不同于組件和 prop，事件名不會被用作一個 JavaScript 變量名或 property 名，所以就沒有理由使用 camelCase 或 PascalCase 了。并且?v-on?事件監聽器在 DOM 模板中會被自動轉換為全小寫 (因為 HTML 是大小寫不敏感的)，所以?v-on:myEvent?將會變成?v-on:myevent——導致?myEvent?不可能被監聽到。

因此，我們推薦你始終使用 kebab-case 的事件名。

為了區分_原生事件_和_自定義事件_在 Vue 中的使用，建議除了多單詞事件名使用 kebab-case 的情況下，命名還需遵守為?on?+ 動詞?的形式，如下：

<!-- 父組件 --> <div@on-search="handleSearch"@on-clear="handleClear"@on-clickoutside="handleClickOutside"> </div>// 子組件 export default {methods: {handleTriggerItem () {this.$emit('on-clear')}} }

1.3.9?事件方法

• 命名方法：camelCase

• 命名規范：handle + 名稱（可選）+ 動詞

<template><el-pagination@size-change="handleSizeChange"@current-change="handleCurrentChange":current-page.sync="currentPage1":page-size="100"layout="total, prev, pager, next":total="1000"></el-pagination> </template><script>export default {methods: {handleSizeChange() {//...},handleCurrentChange() {//...}} } </script>

• 命名方法：camelCase

• 命名規范：動詞+名詞

<template><div @click="setMatrixNum"></div> </template><script>export default {methods: {setMatrixNum() {//...},} } </script>

二、代碼規范

2.1 Vue? 主要針對vue2.x

2.1.1 代碼結構??

<template><div id="my-component"><HelloComponent /><ys-video></ys-video></div> </template><script> import HelloComponent from '../components/HelloComponent' import YsVideo '../components/YsVideo 'export default {name: 'MyComponent',components: {HelloComponent,YsVideo},mixins: [],props: {},data () {return {}},computed: {},watch: {}created () {},mounted () {},destroyed () {},methods: {}, } </script><style lang="scss" scoped> #my-component { } </style>

2.1.2 data

組件的?data?必須是一個函數。

// xxx.vue export default {data () {return {foo: 'bar'}} }

2.1.3 prop

Prop 定義應該盡量詳細。

export default {props: {status: {type: String,required: true,},number:{type:[String,Number,Boolean,Array,Object,Date,Function,Symbol],default: function () {return { }}},string: {type: String,required: true,validator: function (value) {return ['syncing', 'synced','version-conflict','error'].indexOf(value) !== -1}}} }

2.1.4 computed

應該把復雜計算屬性分割為盡可能多的更簡單的屬性。?小的、專注的計算屬性減少了信息使用時的假設性限制，所以需求變更時也用不著那么多重構了。

// bad computed: { price: function () { var basePrice = this.price1 / (1 - this.num) return ( basePrice - basePrice * (this.discountPercent || 0) ) } }// good computed: {basePrice: function () {return this.price1 / (1 - this.num)},discount: function () {return this.basePrice * (this.discountPercent || 0)},finalPrice: function () {return this.basePrice - this.discount} }

2.1.5 為?v-for?設置鍵值

在組件上必須用?key?搭配?v-for，以便維護內部組件及其子樹的狀態。甚至在元素上維護可預測的行為，比如動畫中的對象固化 (object constancy)

<ul><liv-for="todo in todos":key="todo.id">{{ todo.text }}</li> </ul>

2.1.6?v-if?和?v-for?互斥

永遠不要把?v-if?和?v-for?同時用在同一個元素上。

報錯信息：The 'users' variable inside 'v-for' directive should be replaced with a computed property that returns filtered array instead. You should not mix 'v-for' with 'v-if'.<ul><liv-for="user in users"v-if="shouldShowUsers":key="user.id">{{ user.name }}</li> </ul>

一般我們在兩種常見的情況下會傾向于這樣做：

• 為了過濾一個列表中的項目 (比如?v-for="user in users" v-if="user.isActive")。在這種情形下，請將?users?替換為一個計算屬性 (比如?activeUsers)，讓其返回過濾后的列表。

<ul><liv-for="user in activeUsers":key="user.id">{{ user.name }}</li> </ul>computed: {activeUsers: function () {return this.users.filter((user) => {return user.isActive})} }

• 為了避免渲染本應該被隱藏的列表 (比如?v-for="user in users" v-if="shouldShowUsers")。這種情形下，請將?v-if?移動至容器元素上 (比如?ul,?ol)。

<!-- bad --> <ul><liv-for="user in users"v-if="shouldShowUsers":key="user.id">{{ user.name }}</li> </ul><!-- good --> <ul v-if="shouldShowUsers"><liv-for="user in users":key="user.id">{{ user.name }}</li> </ul><!-- good --> <template v-for="(item,index) in checkList"><div :key="index" v-if="item.status" :label="item.name"> </div> </template>

2.1.7 多個 attribute 的元素

建議：多個 attribute 的元素應該分多行撰寫，每個 attribute 一行。視情況而定

<!-- bad --> <img src="https://vuejs.org/images/logo.png" alt="Vue Logo"> <MyComponent foo="a" bar="b" baz="c"/><!-- good --> <imgsrc="https://vuejs.org/images/logo.png"alt="Vue Logo"><MyComponentfoo="a"bar="b"baz="c"/>

2.1.8 模板中簡單的表達式

組件模板應該只包含簡單的表達式，復雜的表達式則應該重構為計算屬性或方法。

復雜表達式會讓你的模板變得不那么聲明式。我們應該盡量描述應該出現的是什么，而非如何計算那個值。而且計算屬性和方法使得代碼可以重用。

// bad <!-- 在模板中 --> {{fullName.split(' ').map((word) => {return word[0].toUpperCase() + word.slice(1)}).join(' ') }}//good <!-- 在模板中 --> {{ normalizedFullName }}// 復雜表達式已經移入一個計算屬性 computed: {normalizedFullName: function () {return this.fullName.split(' ').map(function (word) {return word[0].toUpperCase() + word.slice(1)}).join(' ')} }

2.1.9 帶引號的 attribute 值

非空 HTML 特性值應該始終帶雙引號。

<!-- bad --> <input type=text> <AppSidebar :style={width:sidebarWidth+'px'}><!-- good --> <input type="text"> <AppSidebar :style="{ width: sidebarWidth + 'px' }">

2.1.10 指令縮寫

• 用?:?表示?v-bind:

• 用?@?表示?v-on:

• 用?#?表示?v-slot:

<input:value="newTodoText":placeholder="newTodoInstructions"><input@input="onInput"@focus="onFocus"><template #header><h1>Here might be a page title</h1> </template><template #footer><p>Here's some contact info</p> </template>

2.2 HTML

2.2.1 文件模板

HTML5 文件模板：

<!DOCTYPE html><html lang="zh-CN"><head><meta charset="UTF-8"><title>HTML5標準模版</title></head><body></body> </html>

移動端：

<!DOCTYPE html> <html lang="zh-CN"> <head><meta charset="UTF-8"><meta name="viewport"content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, shrink-to-fit=no"><meta name="format-detection" content="telephone=no"><title>移動端HTML模版</title><!-- S DNS預解析 --><link rel="dns-prefetch" href=""><!-- E DNS預解析 --><!-- S 線上樣式頁面片，開發請直接取消注釋引用 --><!-- #include virtual="" --><!-- E 線上樣式頁面片 --><!-- S 本地調試，根據開發模式選擇調試方式，請開發刪除 --><link rel="stylesheet" href="css/index.css"><!-- /本地調試方式 --><link rel="stylesheet" href="http://srcPath/index.css"><!-- /開發機調試方式 --><!-- E 本地調試 --></head> <body> </body> </html>

PC 端：

<!DOCTYPE html> <html lang="zh-CN"> <head><meta charset="UTF-8"><meta name="keywords" content="your keywords"><meta name="description" content="your description"><meta name="author" content="author,email address"><meta name="robots" content="index,follow"><meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1"><meta name="renderer" content="ie-stand"><title>PC端HTML模版</title><!-- S DNS預解析 --><link rel="dns-prefetch" href=""><!-- E DNS預解析 --><!-- S 線上樣式頁面片，開發請直接取消注釋引用 --><!-- #include virtual="" --><!-- E 線上樣式頁面片 --><!-- S 本地調試，根據開發模式選擇調試方式，請開發刪除 --><link rel="stylesheet" href="css/index.css"><!-- /本地調試方式 --><link rel="stylesheet" href="http://srcPath/index.css"><!-- /開發機調試方式 --><!-- E 本地調試 --> </head> <body> </body> </html>

2.2.2 元素及標簽閉合

HTML 元素共有以下5種：

• 空元素：area、base、br、col、command、embed、hr、img、input、keygen、link、meta、param、source、track、wbr

• 原始文本元素：script、style

• RCDATA 元素：textarea、title

• 外來元素：來自 MathML 命名空間和 SVG 命名空間的元素

• 常規元素：其他 HTML 允許的元素都稱為常規元素

為了能讓瀏覽器更好的解析代碼以及能讓代碼具有更好的可讀性，有如下約定：

• 所有具有開始標簽和結束標簽的元素都要寫上起止標簽，某些允許省略開始標簽或和束標簽的元素亦都要寫上。

• 空元素標簽都不加 “/” 字符。

<!-- good --> <div><h1>我是h1標題</h1><p>我是一段文字，我有始有終，瀏覽器能正確解析</p> </div><br data-tomark-pass><!-- bad --> <div><h1>我是h1標題</h1><p>我是一段文字，我有始無終，瀏覽器亦能正確解析 </div><br/>

2.2.3 代碼嵌套

元素嵌套規范，每個塊狀元素獨立一行，內聯元素可選。

<!-- good --> <div><h1></h1><p></p> </div> <p><span></span><span></span></p><!-- bad --> <div><h1></h1><p></p> </div> <p> <span></span><span></span> </p>

段落元素與標題元素只能嵌套內聯元素。

<!-- good --> <h1><span></span></h1> <p><span></span><span></span></p><!-- bad --> <h1><div></div></h1> <p><div></div><div></div></p>

2.3 CSS

2.3.1 樣式文件

樣式文件必須寫上?@charset?規則，并且一定要在樣式文件的第一行首個字符位置開始寫，編碼名用?“UTF-8”。

• 推薦：

@charset "UTF-8"; .jdc {}

• 不推薦：

/* @charset規則不在文件首行首個字符開始 */ @charset "UTF-8"; .jdc {}/* @charset規則沒有用小寫 */ @CHARSET "UTF-8"; .jdc {}/* 無@charset規則 */ .jdc {}

2.3.2 代碼格式化

樣式書寫一般有兩種：一種是緊湊格式 （Compact），一種是展開格式（Expanded）。

• 推薦：展開格式（Expanded）

.jdc {display: block;width: 50px; }

• 不推薦：緊湊格式 （Compact）

.jdc { display: block; width: 50px;}

2.3.3 代碼大小寫

樣式選擇器，屬性名，屬性值關鍵字全部使用小寫字母書寫，屬性字符串允許使用大小寫。

//good .jdc {display: block; }//bad.JDC {DISPLAY: BLOCK; }

2.3.4 代碼易讀性

????????1、左括號與類名之間一個空格，冒號與屬性值之間一個空格。

推薦 .jdc {width: 100%; }不推薦 .jdc{width:100%; }

? ? ? ? 2、逗號分隔的取值，逗號之后一個空格。

推薦 .jdc {box-shadow: 1px 1px 1px #333, 2px 2px 2px #ccc; } 不推薦 .jdc {box-shadow: 1px 1px 1px #333,2px 2px 2px #ccc; }

? ? ? ? 3、為單個 CSS 選擇器或新聲明開啟新行。

推薦 .jdc, .jdc_logo, .jdc_hd {color: #ff0; }.nav{color: #fff; }不推薦 .jdc, .jdc_logo, .jdc_hd {color: #ff0; }.nav{color: #fff; }

? ? ? ? 4、顏色值?rgb()?rgba()?hsl()?hsla()?rect()?中不需有空格，且取值不要帶有不必要的 0。

推薦 .jdc {color: rgba(255,255,255,.5); }不推薦 .jdc {color: rgba( 255, 255, 255, 0.5 ); }

? ? ? ? 5、屬性值十六進制數值能用簡寫的盡量用簡寫

推薦 .jdc {color: #fff; } 不推薦 .jdc {color: #ffffff; }

? ? ? ? 6、不要為?0?指明單位

推薦 .jdc {margin: 0 10px; }不推薦 .jdc {margin: 0px 10px; }

2.3.5 屬性值引號

CSS 屬性值需要用到引號時，統一使用單引號。

推薦 .jdc {font-family: 'Hiragino Sans GB'; }不推薦 .jdc {font-family: "Hiragino Sans GB"; }

2.3.6 屬性書寫建議

建議遵循以下順序：

布局定位屬性：display / position / float / clear / visibility / overflow

自身屬性：width / height / margin / padding / border / background

文本屬性：color / font / text-decoration / text-align / vertical-align / white- space / break-word

其他屬性（CSS3）：content / cursor / border-radius / box-shadow / text-shadow / background: linear-gradient …

.jdc {display: block;position: relative;float: left;width: 100px;height: 100px;margin: 0 10px;padding: 20px 0;font-family: Arial, 'Helvetica Neue', Helvetica, sans-serif;color: #333;background: rgba(0,0,0,.5);-webkit-border-radius: 10px;-moz-border-radius: 10px;-o-border-radius: 10px;-ms-border-radius: 10px;border-radius: 10px; }

3.3.7 CSS3 瀏覽器私有前綴

CSS3 瀏覽器私有前綴在前，標準前綴在后。

.jdc {-webkit-border-radius: 10px;-moz-border-radius: 10px;-o-border-radius: 10px;-ms-border-radius: 10px;border-radius: 10px; }

2.4 JavaScript

2.4.1 單行代碼塊

在單行代碼塊中使用空格。

推薦 function foo () { return true } if (foo) { bar = 0 }不推薦 function foo () {return true} if (foo) {bar = 0}

2.4.2 大括號風格

在編程過程中，大括號風格與縮進風格緊密聯系，用來描述大括號相對代碼塊位置的方法有很多。在 JavaScript 中，主要有三種風格，如下：

• 【推薦】One True Brace Style

if (foo) {bar() } else {baz() }

• Stroustrup

if (foo) {bar() } else {baz() }

• Allman

if (foo) {bar() } else {baz() }

2.4.3 代碼中的空格

? ? ? ? 1、逗號前后的空格可以提高代碼的可讀性，團隊約定在逗號后面使用空格，逗號前面不加空格。

推薦 var foo = 1, bar = 2不推薦 var foo = 1,bar = 2var foo = 1 , bar = 2var foo = 1 ,bar = 2

? ? ? ? 2、對象字面量的鍵和值之間不能存在空格，且要求對象字面量的冒號和值之間存在一個空格。

推薦 var obj = { 'foo': 'haha' }不推薦 var obj = { 'foo' : 'haha' }

????????3、代碼塊前要添加空格

推薦 if (a) {b() }function a() {}不推薦 if (a){b() }function a (){}

????????4、在函數調用時，禁止使用空格

推薦 fn()不推薦 fn ()fn ()

????????5、在操作符前后都需要添加空格。

推薦 var sum = 1 + 2不推薦 var sum = 1+2

三、注釋規范

注釋的目的：

• 提高代碼的可讀性，從而提高代碼的可維護性

注釋的原則：

• 如無必要，勿增注釋 ( As short as possible )

• 如有必要，盡量詳盡 ( As long as necessary )

3.1 HTML 文件注釋

3.1.1 單行注釋

一般用于簡單的描述，如某些狀態描述、屬性描述等。

注釋內容前后各一個空格字符，注釋位于要注釋代碼的上面，單獨占一行。

推薦 <!-- Comment Text --> <div>...</div>不推薦 <div>...</div><!-- Comment Text --><div><!-- Comment Text -->... </div>

3.1.2 模塊注釋

一般用于描述模塊的名稱以及模塊開始與結束的位置。

注釋內容前后各一個空格字符，?<!-- S Comment Text \-->表示模塊開始，?<!-- E Comment Text \-->表示模塊結束，模塊與模塊之間相隔一行。

S：代表開始 E：代表結束

推薦 <!-- S Comment Text A --> <div class="mod_a">... </div> <!-- E Comment Text A --><!-- S Comment Text B --> <div class="mod_b">... </div> <!-- E Comment Text B -->不推薦 <!-- S Comment Text A --> <div class="mod_a">... </div> <!-- E Comment Text A --> <!-- S Comment Text B --> <div class="mod_b">... </div> <!-- E Comment Text B -->

3.1.3 嵌套模塊注釋

當模塊注釋內再出現模塊注釋的時候，為了突出主要模塊，嵌套模塊不再使用。

<!-- S Comment Text A --> <div class="mod_a"><div class="mod_b">...</div><!-- /mod_b --><div class="mod_c">...</div><!-- /mod_c --></div> <!-- E Comment Text A -->

3.2 CSS 文件注釋

3.2.1 單行注釋

注釋內容第一個字符和最后一個字符都是一個空格字符，單獨占一行，行與行之間相隔一行。

推薦 /* Comment Text */ .jdc {} /* Comment Text */ .jdc {}不推薦 /*Comment Text*/ .jdc {display: block; }.jdc {display: block;/*Comment Text*/ }

3.2.2 模塊注釋

注釋內容第一個字符和最后一個字符都是一個空格字符，/*?與 模塊信息描述占一行，多個橫線分隔符?-?與?*/?占一行，行與行之間相隔兩行。

推薦 /* Module A ---------------------------------------------------------------- */ .mod_a {}/* Module B ---------------------------------------------------------------- */ .mod_b {}不推薦 /* Module A ---------------------------------------------------- */ .mod_a {} /* Module B ---------------------------------------------------- */ .mod_b {}

3.2.3 文件注釋

在樣式文件編碼聲明?@charset?語句下面注明頁面名稱、作者、創建日期等信息。

@charset "UTF-8"; /*** @desc File Info* @author Author Name* @date 2015-10-10*/

3.3 JavaScript 文件注釋

3.3.1 單行注釋

單行注釋使用?//，注釋應單獨一行寫在被注釋對象的上方，不要追加在某條語句的后面。

推薦 // is current tab const active = true不推薦 const active = true // is current tab

注釋行的上方需要有一個空行（除非注釋行上方是一個塊的頂部），以增加可讀性

推薦 function getType () { console.log('fetching type...')// set the default type to 'no type'const type = this.type || 'no type'return type }// 注釋行上面是一個塊的頂部時不需要空行 function getType () { // set the default type to 'no type'const type = this.type || 'no type' return type }不推薦 function getType () { console.log('fetching type...')// set the default type to 'no type'const type = this.type || 'no type'return type }

3.3.2 多行注釋

多行注釋使用?/** ... */，而不是多行的?//。

推薦/*** make() returns a new element* based on the passed-in tag name*/ function make (tag) {// ...return element }不推薦 // make() returns a new element // based on the passed in tag name function make (tag) {// ...return element }

3.3.3 注釋空格

注釋內容和注釋符之間需要有一個空格，以增加可讀性。eslint:?spaced-comment。

推薦// is current tab const active = true/*** make() returns a new element* based on the passed-in tag name*/ function make(tag) { // ...return element }不推薦//is current tab const active = true/***make() returns a new element*based on the passed-in tag name*/ function make(tag) { // ...return element }

3.3.4 特殊標記

有時我們發現某個可能的 bug，但因為一些原因還沒法修復；或者某個地方還有一些待完成的功能，這時我們需要使用相應的特殊標記注釋來告知未來的自己或合作者。常用的特殊標記有兩種：

• // FIXME?: 說明問題是什么

  • // TODO?: 說明還要做什么或者問題的解決方案

class Calculator extends Abacus {constructor () {super ()// FIXME: shouldn’t use a global heretotal = 0// TODO: total should be configurable by an options paramthis.total = 0} }

3.3.5 文檔類注釋

文檔類注釋，如函數、類、文件、事件等；都使用 jsdoc 規范。

/*** Book類，代表一個書本.* @constructor* @param {string} title - 書本的標題.* @param {string} author - 書本的作者.*/ function Book (title, author) {this.title = titlethis.author = author }Book.prototype = {/*** 獲取書本的標題* @returns {string|*}*/getTitle: function () {return this.title},/*** 設置書本的頁數* @param pageNum {number} 頁數*/setPageNum: function (pageNum) {this.pageNum=pageNum} }

3.3.6 注釋工具

ESLint?是當下最流行的 JS 代碼檢查工具，ESLint?中有一些注釋相關的規則，用戶可選擇開啟：

• valid-jsdoc

• require-jsdoc

• no-warning-comments

• capitalized-comments

• line-comment-position

• lines-around-comment

• multiline-comment-style

• no-inline-comments

• spaced-comment

四、其它

• 縮進換行請使用兩個空格。

• 大型團隊多人協作項目推薦 JavaScript 代碼末尾加分號。

• 小型個人創新練手項目可嘗試使用 JavaScript 代碼末尾不加分號的風格，更加清爽簡練

?五、GIS規范?

1、GIS框架

Leaflet 是用于移動友好型交互式地圖的領先開源 JavaScript 庫。它可以通過大量插件進行擴展，擁有漂亮、易于使用且文檔齊全的API。

2、目標的渲染

地圖上的目標展示主要使用Marker和Canvas相結合的方式進行渲染。

3、目標軌跡繪制

目標軌跡是一條有方向的軌跡線，主要基于Leaflet中Polyline繪制軌跡線，PolylineDecorator繪制軌跡的方向，Marker繪制軌跡時間點。

4、標繪繪制

通過封裝的MyAngle插件進行標繪的繪制，繪制包括點、線、面。

5、標繪的顯示

標繪分為點、線、面，分別通過Marker、Polyline、Polygon進行顯示。

GIS亮點

1、實時動態渲染大量目標

通過Canvas和Marker相結合的方式進行目標實時的渲染，提高目標動態顯示的性能。

2、快速便捷地進行標繪繪制

標繪的經緯度坐標點的錄入同時支持兩種格式，即數值類型和度分秒格式；繪制的每個標繪點都有與之對應的坐標點位，可以精確地查看當前坐標點位置。

3、實時軌跡和動態軌跡回放

可以渲染當前目標的實時軌跡；可以形象地通過動畫回放當前的軌跡。

4、實時顯示視頻設備的可視范圍

實時展示設備可視范圍，調整視頻設備的狀態，可以實時地反饋在地圖上。

六、移動端app、小程序規范

后續補充....

總結

以上是生活随笔為你收集整理的Vue 前端代码风格指南、代码规范的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。