js 代码规范

之前在公司分享的内容，这里测试下

Transcript

1. 由于光云前端团队的扩张趋势，将来一定会遇到团队代码维护成本的问题，而统一的代码风格会提升 大量工作效率，势在必行。愿景是让每个人在改别人代码的时候，不再那么抓狂！ 变量声明必须加var关键字，严格控制作用域； 变量声明全部集中在顶部，禁止在块级代码中声明变量，如if(true) {var a = 0;}; 建议使用驼峰式命名变量和函数，如：functionNamesLikeThis,ClassNamesLikeThis； 私有成员变量和方法命名以下划线开头，如： v a r _ t h i s ； 常量定义单词全部大写，以下划线连接，但不要用const关键字来声明，如： SOME_CONSTANTS，全局变量也用这种命名方式 jquery的dom变量，用$开头，如：var $input = $('input'); 函数参数大于3个时，应以对象形式作为参数集传递, API特殊处理； 禁止在代码块中声明函数，错误的范例：if (true) {function foo() {}}； 禁止用new来实例化基本类型，错误的范例：var x = new Boolean(false)；正则不在范围内 直接定义数组或对象，而不使用new关键字声明，错误的范例：var a = new Array();var o = new Object()； 使用单引号''来定义字符串； 文件名必须全部用小写，文件名分隔符用中划线连接，版本连接符用实心点,如：passport- core.min.js。且使用常用的英文，避免使用拼音首字母拼接 函数表达式（有别于函数声明，如：function x(){}）必须用分号结束，下面是错误的范例，第三行漏 背景 基本规范 分号
2. 掉分号，后面的函数被当作参数传递给myMethod，导致解析错误： v a r m y M e t h o d = f u n c t i o n ( ) { r e t u r n 4 2 ; } ( f u n c t i o n ( ) { / / 一个匿名函数，在这里会被错误解析当作参数调用导致报错 } ) ( ) ; 由于无法完美的控制都不出现异常，所以尽量在可能但不确定出现异常的地方（大量运算，AJAX请 求，数组操作或DOM操作等）用try-catch(e)来抛出异常，这样有利于规模较大的项目中排查错误。 使用自定义异常抛出错误信息，更有利于错误信息阅读，且更加通用，因为不同浏览器抛出的信息不 一样，有时候可能很难定位到问题所在位置，特别是IE下可能遇到的如下报错信息： S t a c k o v e r f l o w a t l i n e : 0 或： 未知的运行时错误 不使用with关键字，容易造成作用域混乱； 通用全局函数，特别是通用组件代码应将业务逻辑放入闭包中，并通过“命名空间”将其引入； 若函数中使用到全局变量，则访问全局变量时应使用window来引入，如： v a r s o m e v a r = 1 0 ； f u n c t i o n g e t v a r ( ) { v a r n u m = w i n d o w . s o m e v a r + 1 ; / / . . . 异常 作用域相关
3. r e t u r n n u m ; } 没有强制要求代码需格式化成什么样子，但尽量使代码具有较高的可读性。下面给出一些建议的代码 风格： / / 花括号起始位置与语句开始在同一行 i f ( s o m e t h i n g ) { / / . . . } e l s e { / / . . . } / / 数组和对象书写 v a r a r r = [ 1 , 2 , 3 ] ; / / [ 之后，] 之前没有空格 v a r o b j = { a : 1 , b : 2 , c : 3 } ; / / { 之后，} 之前没有空格 / / 多行数组和对象书写 v a r a = [ ' h u a n g r o n g r o n g ' , ' c h e n y i n g ' , ' s m a l l g r e y g r e y ' , ' s h e n s h u n l i n ' ] ; v a r p o s = { t o p : 1 0 , r i g h t : 2 0 , b o t t o m : 1 5 , l e f t : 1 2 } ; 格式化代码
4. / / 将业务逻辑相关的代码写一起，不相关的以空行分隔 d o S o m e t h i n g T o ( x ) ; d o S o m e t h i n g E l s e T o ( x ) ; a n d T h e n ( x ) ; n o w D o S o m e t h i n g W i t h ( y ) ; a n d N o w W i t h ( z ) ; v a r x = a ? b : c ; / / 一行能写完, 一行8 0 个字符左右 / / 写不完可以换行加缩进 v a r y = a ? l o n g B u t S i m p l e O p e r a n d B : l o n g B u t S i m p l e O p e r a n d C ; / / 或者这样 v a r z = a ? m o r e C o m p l i c a t e d B : m o r e C o m p l i c a t e d C ; 对于代码中需要进行==逻辑判断的变量，建议进行强制类型转换或使用===代替。 下列值在布尔表达式中结果为false： null undefined '' //空字符串 0 //数字 而下面的为true： '0' //字符串 类型转换
5. [] //空数组 {} //空对象 平时开发： 单行注释使用//，多行使用/* ... */； 注释名词：TODO-将要做的；HACK-用了些坑爹的技巧，必须详细描述下 BUG-要及时解决的 FIXME-现在没办法只能先这样 建议加入开发者个人信息及最后修改时间注释，虽然这些信息不会被YUIDoc解析显示； 组件开发： 文档注释遵循YUIDoc规范（http://yui.github.io/yuidoc/syntax/），所有的文件、类、方法和属性都 应该用合适的标记和类型进行注释。 YUIDoc要求文档中至少要有一个class和constructor标记来定义类和构造函数； YUIDoc中注释块必须以/**（至少两个星号）开头； 方法、参数和返回值等必须有注释说明； 下面给出代码注释实例作为参考，更多标记和类型定义请参考YUIDoc官方文档。 / * * 这是一个M y C l a s s 类 @ c l a s s M y C l a s s @ c o n s t r u c t o r @ a u t h o r x x < x x @ g m a i l . c o m > @ m o d i f i e d s o m e o n e @ d a t e 2 0 1 5 ‐ 0 6 ‐ 0 3 * * / 注释规范
6. f u n c t i o n M y C l a s s = f u n c t i o n ( ) { } ; / * * M y m e t h o d d e s c r i p t i o n . L i k e o t h e r p i e c e s o f y o u r c o m m e n t b l o c k s , t h i s c a n s p a n m u l t i p l e l i n e s . @ m e t h o d c s s @ p a r a m p r o p { S t r i n g } s e t / g e t a c s s p r o p e r t y @ p a r a m [ v a l u e ] { S t r i n g } A v a l u e y o u w a n t t o s e t t o a c s s p r o p e r t y @ e x a m p l e e l e . c s s ( ' w i d t h ' , ' 1 0 0 % ' ) ; @ r e t u r n { B o o l e a n } R e t u r n s t r u e o n s u c c e s s * * / M y C l a s s . p r o t o t y p e . c s s = f u n c t i o n ( p r o p , v a l u e ) { } ; 取消strict模式，加入raycloud全局变量 { / / J S H i n t D e f a u l t C o n f i g u r a t i o n F i l e ( a s o n J S H i n t w e b s i t e ) / / S e e h t t p : / / j s h i n t . c o m / d o c s / f o r m o r e d e t a i l s " m a x e r r " : 5 0 , / / { i n t } M a x i m u m e r r o r b e f o r e s t o p p i n g / / E n f o r c i n g " b i t w i s e " : t r u e , / / t r u e : P r o h i b i t b i t w i s e o p e r a t o r s ( & , | , ^ , e t c . ) " c a m e l c a s e " : f a l s e , / / t r u e : I d e n t i f i e r s m u s t b e i n c a m e l C a s e " c u r l y " : t r u e , / / t r u e : R e q u i r e { } f o r e v e r y n e w b l o c k o r s c o p e " e q e q e q " : t r u e , / / t r u e : R e q u i r e t r i p l e e q u a l s ( = = = ) f o r c o m p a r i s o n " f o r i n " : t r u e , / / t r u e : R e q u i r e f i l t e r i n g f o r . . i n l o o p s w i t h o b j . h a s O w n P r o p e r t y ( ) " f r e e z e " : t r u e , / / t r u e : p r o h i b i t s o v e r w r i t i n g p r o t o t y p e s o f n a t i v e o b j e c t s s u c h a s A r r a y , D " i m m e d " : f a l s e , / / t r u e : R e q u i r e i m m e d i a t e i n v o c a t i o n s t o b e w r a p p e d i n p a r e n s e . g . ` ( f u n c t i JSHint配置
7. " i n d e n t " : 4 , / / { i n t } N u m b e r o f s p a c e s t o u s e f o r i n d e n t a t i o n " l a t e d e f " : f a l s e , / / t r u e : R e q u i r e v a r i a b l e s / f u n c t i o n s t o b e d e f i n e d b e f o r e b e i n g u s e d " n e w c a p " : f a l s e , / / t r u e : R e q u i r e c a p i t a l i z a t i o n o f a l l c o n s t r u c t o r f u n c t i o n s e . g . ` n e w F ( ) ` " n o a r g " : t r u e , / / t r u e : P r o h i b i t u s e o f ` a r g u m e n t s . c a l l e r ` a n d ` a r g u m e n t s . c a l l e e ` " n o e m p t y " : t r u e , / / t r u e : P r o h i b i t u s e o f e m p t y b l o c k s " n o n b s p " : t r u e , / / t r u e : P r o h i b i t " n o n ‐ b r e a k i n g w h i t e s p a c e " c h a r a c t e r s . " n o n e w " : f a l s e , / / t r u e : P r o h i b i t u s e o f c o n s t r u c t o r s f o r s i d e ‐ e f f e c t s ( w i t h o u t a s s i g n m e n t ) " p l u s p l u s " : f a l s e , / / t r u e : P r o h i b i t u s e o f ` + + ` & ` ‐ ‐ ` " q u o t m a r k " : f a l s e , / / Q u o t a t i o n m a r k c o n s i s t e n c y : / / f a l s e : d o n o t h i n g ( d e f a u l t ) / / t r u e : e n s u r e w h a t e v e r i s u s e d i s c o n s i s t e n t / / " s i n g l e " : r e q u i r e s i n g l e q u o t e s / / " d o u b l e " : r e q u i r e d o u b l e q u o t e s " u n d e f " : t r u e , / / t r u e : R e q u i r e a l l n o n ‐ g l o b a l v a r i a b l e s t o b e d e c l a r e d ( p r e v e n t s g l o b a l l e " u n u s e d " : t r u e , / / U n u s e d v a r i a b l e s : / / t r u e : a l l v a r i a b l e s , l a s t f u n c t i o n p a r a m e t e r / / " v a r s " : a l l v a r i a b l e s o n l y / / " s t r i c t " : a l l v a r i a b l e s , a l l f u n c t i o n p a r a m e t e r s " s t r i c t " : f a l s e , / / t r u e : R e q u i r e s a l l f u n c t i o n s r u n i n E S 5 S t r i c t M o d e " m a x p a r a m s " : f a l s e , / / { i n t } M a x n u m b e r o f f o r m a l p a r a m s a l l o w e d p e r f u n c t i o n " m a x d e p t h " : f a l s e , / / { i n t } M a x d e p t h o f n e s t e d b l o c k s ( w i t h i n f u n c t i o n s ) " m a x s t a t e m e n t s " : f a l s e , / / { i n t } M a x n u m b e r s t a t e m e n t s p e r f u n c t i o n " m a x c o m p l e x i t y " : f a l s e , / / { i n t } M a x c y c l o m a t i c c o m p l e x i t y p e r f u n c t i o n " m a x l e n " : f a l s e , / / { i n t } M a x n u m b e r o f c h a r a c t e r s p e r l i n e / / R e l a x i n g " a s i " : f a l s e , / / t r u e : T o l e r a t e A u t o m a t i c S e m i c o l o n I n s e r t i o n ( n o s e m i c o l o n s ) " b o s s " : f a l s e , / / t r u e : T o l e r a t e a s s i g n m e n t s w h e r e c o m p a r i s o n s w o u l d b e e x p e c t e d " d e b u g " : f a l s e , / / t r u e : A l l o w d e b u g g e r s t a t e m e n t s e . g . b r o w s e r b r e a k p o i n t s . " e q n u l l " : f a l s e , / / t r u e : T o l e r a t e u s e o f ` = = n u l l ` " e s 5 " : f a l s e , / / t r u e : A l l o w E S 5 s y n t a x ( e x : g e t t e r s a n d s e t t e r s ) " e s n e x t " : f a l s e , / / t r u e : A l l o w E S . n e x t ( E S 6 ) s y n t a x ( e x : ` c o n s t ` ) " m o z " : f a l s e , / / t r u e : A l l o w M o z i l l a s p e c i f i c s y n t a x ( e x t e n d s a n d o v e r r i d e s e s n e x t f e a t u r / / ( e x : ` f o r e a c h ` , m u l t i p l e t r y / c a t c h , f u n c t i o n e x p r e s s i o n … ) " e v i l " : f a l s e , / / t r u e : T o l e r a t e u s e o f ` e v a l ` a n d ` n e w F u n c t i o n ( ) ` " e x p r " : f a l s e , / / t r u e : T o l e r a t e ` E x p r e s s i o n S t a t e m e n t ` a s P r o g r a m s " f u n c s c o p e " : f a l s e , / / t r u e : T o l e r a t e d e f i n i n g v a r i a b l e s i n s i d e c o n t r o l s t a t e m e n t s " g l o b a l s t r i c t " : f a l s e , / / t r u e : A l l o w g l o b a l " u s e s t r i c t " ( a l s o e n a b l e s ' s t r i c t ' )
8. " i t e r a t o r " : f a l s e , / / t r u e : T o l e r a t e u s i n g t h e ` _ _ i t e r a t o r _ _ ` p r o p e r t y " l a s t s e m i c " : f a l s e , / / t r u e : T o l e r a t e o m i t t i n g a s e m i c o l o n f o r t h e l a s t s t a t e m e n t o f a 1 ‐ l i n e b " l a x b r e a k " : f a l s e , / / t r u e : T o l e r a t e p o s s i b l y u n s a f e l i n e b r e a k i n g s " l a x c o m m a " : f a l s e , / / t r u e : T o l e r a t e c o m m a ‐ f i r s t s t y l e c o d i n g " l o o p f u n c " : f a l s e , / / t r u e : T o l e r a t e f u n c t i o n s b e i n g d e f i n e d i n l o o p s " m u l t i s t r " : f a l s e , / / t r u e : T o l e r a t e m u l t i ‐ l i n e s t r i n g s " n o y i e l d " : f a l s e , / / t r u e : T o l e r a t e g e n e r a t o r f u n c t i o n s w i t h n o y i e l d s t a t e m e n t i n t h e m . " n o t y p e o f " : f a l s e , / / t r u e : T o l e r a t e i n v a l i d t y p e o f o p e r a t o r v a l u e s " p r o t o " : f a l s e , / / t r u e : T o l e r a t e u s i n g t h e ` _ _ p r o t o _ _ ` p r o p e r t y " s c r i p t u r l " : f a l s e , / / t r u e : T o l e r a t e s c r i p t ‐ t a r g e t e d U R L s " s h a d o w " : f a l s e , / / t r u e : A l l o w s r e ‐ d e f i n e v a r i a b l e s l a t e r i n c o d e e . g . ` v a r x = 1 ; x = 2 ; ` " s u b " : f a l s e , / / t r u e : T o l e r a t e u s i n g ` [ ] ` n o t a t i o n w h e n i t c a n s t i l l b e e x p r e s s e d i n d o t " s u p e r n e w " : f a l s e , / / t r u e : T o l e r a t e ` n e w f u n c t i o n ( ) { . . . } ; ` a n d ` n e w O b j e c t ; ` " v a l i d t h i s " : f a l s e , / / t r u e : T o l e r a t e u s i n g t h i s i n a n o n ‐ c o n s t r u c t o r f u n c t i o n / / E n v i r o n m e n t s " b r o w s e r " : t r u e , / / W e b B r o w s e r ( w i n d o w , d o c u m e n t , e t c ) " b r o w s e r i f y " : f a l s e , / / B r o w s e r i f y ( n o d e . j s c o d e i n t h e b r o w s e r ) " c o u c h " : f a l s e , / / C o u c h D B " d e v e l " : t r u e , / / D e v e l o p m e n t / d e b u g g i n g ( a l e r t , c o n f i r m , e t c ) " d o j o " : f a l s e , / / D o j o T o o l k i t " j a s m i n e " : f a l s e , / / J a s m i n e " j q u e r y " : t r u e , / / j Q u e r y " m o c h a " : t r u e , / / M o c h a " m o o t o o l s " : f a l s e , / / M o o T o o l s " n o d e " : f a l s e , / / N o d e . j s " n o n s t a n d a r d " : f a l s e , / / W i d e l y a d o p t e d g l o b a l s ( e s c a p e , u n e s c a p e , e t c ) " p h a n t o m " : f a l s e , / / P h a n t o m J S " p r o t o t y p e j s " : f a l s e , / / P r o t o t y p e a n d S c r i p t a c u l o u s " q u n i t " : f a l s e , / / Q U n i t " r h i n o " : f a l s e , / / R h i n o " s h e l l j s " : f a l s e , / / S h e l l J S " t y p e d " : f a l s e , / / G l o b a l s f o r t y p e d a r r a y c o n s t r u c t i o n s " w o r k e r " : f a l s e , / / W e b W o r k e r s " w s h " : f a l s e , / / W i n d o w s S c r i p t i n g H o s t " y u i " : f a l s e , / / Y a h o o U s e r I n t e r f a c e / / C u s t o m G l o b a l s
9. 每个项目根目录下，添加一个README.md;记录项目启动方式(start up)，参考资料等等 语法使用MarkDown，因为它有以下优点： 阅读优雅 书写简便 通用化 这里有个在线编辑器分享 ppt 腾讯前端代码规范 《编写可维护的javascript》 《编写可读代码的艺术》 " g l o b a l s " : { " R a y C l o u d " : t r u e , " d e f i n e " : t r u e , " r e q u i r e " : t r u e } / / a d d i t i o n a l p r e d e f i n e d g l o b a l v a r i a b l e s } 文档规范 参考文档