>

中哪些是好的注释,LessCss学习笔记

- 编辑:至尊游戏网站 -

中哪些是好的注释,LessCss学习笔记

在 css 中哪些是好的注释?

2018/02/28 · CSS · 注释

初藳出处: Keith J. Grant   译文出处:[众成翻译

  • KING]()   

图片 1
Robert C. Martin写的《Clean Code》是自家读过的最佳的编制程序书籍之生机勃勃,若没有读过,推荐你将它走入书单。

表明就象征代码不或然自表明 —— 罗Bert C. 马丁

马丁在文中详尽批评了代码注释,小编不会完全重复他的话。说来讲去,他的情趣便是,那个注释是决定会过时的。程序实践时会忽略注释,所以一点都不大概保障这一个验证注释会标准的陈诉代码作用。所以最佳的主意是让代码自表达,如此,根据代码逻辑,技师和次序得到到的新闻是同等的。

合计如下代码:

// Check to see if the employee is eligible for full benefits // 检查工作者是不是有身份获得全体有益于 if ((employee.flags & HOUCRUISERLY_FLAG) && (employee.age > 65)) { … }

1
2
3
4
5
// Check to see if the employee is eligible for full benefits
// 检查员工是否有资格获取全部福利
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65)) {
  …
}

讲授有用么?当然有用,但上边包车型客车章程大概更好:

if (employee.isEligibleForFullBenefits()) { … }

1
2
3
if (employee.isEligibleForFullBenefits()) {
  …
}

代码须要“言行豆蔻梢头致”,注释是能够被命名优越的函数或变量替代的。Martin的意思实际不是说不用使用注释,而是应该尽量防止写注释,注释就象征代码不能够自表达。

一、入门

那么对CSS而言呢?

本人十三分支持马丁关于注释的意见。当提到到注脚式的语言如CSS时,就开掘了有个别风趣的地点。证明式语言式必需切合影应格式的,而CSS选用器基本是由HTML结构决定的。对这种代码结构,大家能做的非常少,那是否意味CSS代码必得注释满天飞?

额,可能吧。有广大的理由使用注释,且注释的写法也是有无数。让大家来看一些疏解,构思那些注释是还是不是应当加上。先从答案明确的始发吧,然后一步步无时或忘到不那么好剖断的。

不佳:多此一举的笺注


其他语言,多此一举的注脚都是剩下的,如下的演示出自Bootstrap3的最先版本:

// Addresses address {…}

1
2
// Addresses
address {…}

肯定,address是关于地点的接受器

// Unordered and Ordered lists ul, ol {…}

1
2
3
// Unordered and Ordered lists
ul,
ol {…}

还有?

// Blockquotes blockquote {…}

1
2
// Blockquotes
blockquote {…}

赶紧停!

纯属不要写那种注释,赶紧删掉那么些多余的事物,它独自是在重复代码而已。当然,新本子的Bootstrap已经删除掉抢先四分之二多此一举的不算注释了。

1、LESSCSS是什么?

LESSCSS是风流倜傥种动态样式语言,归属CSS预管理语言的风度翩翩种,它使用形似CSS的语法,为CSS的授予了动态语言的特色,如变量、世袭、运算、函数等,更便于CSS的编纂和护卫。

LESSCSS能够在二种语言、情形中利用,包涵浏览器端(补助IE6+, Webkit, Firefox卡塔尔国、桌面客户端、服务端。

例如:

@color:#4D926F;
p{
  color: @color;
}

编译成:

p{
  color: #4D926F;
}

倒霉: 块分隔注释

对CSS来讲,块分隔注释是不行独特的,如下:

/* ----------------- * TOOLTIPS * ----------------- */

1
2
3
/* -----------------
* TOOLTIPS
* ----------------- */

这种注释能把自家逼疯。笔者能体会精晓为啥会写下这种注释:一时候大家的CSS会写得特别长,当在超越千行的公文内搜索时,就要求这种带特殊标记的讲解来增派急速寻觅。

但骨子里,非常短相当短的CSS文件已经不再流行了。若您的连串实在需求这种相当的大的CSS文件,它应当是由四个小的有些,通过CSS预管理工科具组合而成的。

2、使用LESSCSS

不佳:解释语法

又要用Bootstrap举例了,以下代码出自 _tooltips.scss:

// Allow breaking very long words so they don't overflow the tooltip's bounds // 设置长单词换行 word-wrap: break-word;

1
2
3
// Allow breaking very long words so they don't overflow the tooltip's bounds
// 设置长单词换行
word-wrap: break-word;

这种艺术和“画蛇添足的笺注”近似,注释解释word-wrap属性的功用。这里有黄金时代篇随笔讲到这种注释为啥没有必要的来头,疏解应该表明“为何”,并非“是如何”,即表明原因此不是表达效果与利益(Why, not what卡塔 尔(阿拉伯语:قطر‎。

此地有叁个不及,由于CSS有成都百货上千天性,只怕有些属性是你完全不知晓的,那么您用这种注释是符合规律的。

1卡塔 尔(阿拉伯语:قطر‎顾客端应用

在浏览器中央银行使less.js是极度便于的,但是这种措施不建议用于临盆。在生产中,提议选用node.js或然第三方工具进行预编写翻译。

首先,链接.less文件,设置rel属性为"stylesheet/less":

<link rel="stylesheet/less" type="text/css" href="styles.less" />

接着,下载less.js,或者到官网下载最新的,包含在<script></script>标签中:

<script src="less.js" type="text/javascript"></script>

也能够选择Less CDN:

<script src="//cdnjs.cloudflare.com/ajax/libs/less.js/2.5.3/less.min.js"></script>

在 <script src="less.js"></script> 此前设置全局的的less对象:

<!-- set options before less.js script -->
<script>
  less = {
    env: "development",
    async: false,
    fileAsync: false,
    poll: 1000,
    functions: {},
    dumpLineNumbers: "comments",
    relativeUrls: false,
    rootpath: ":/a.com/"
  };
</script>
<script src="less.js"></script>

意:确认保证在引用脚本从前援用样式文件。

点击以下链接下载上述代码:LESSCSS入门demo

不佳:对库举办介绍

正如是Bootstrap tooltips.scss文件的另大器晚成段注释:

// Our parent element can be arbitrary since tooltips are by default inserted as a // sibling of their target element. So reset our font and text properties to avoid // inheriting weird values. // 由于提示框会被默许插入到对象成分后作为三个男子成分, // 所以必要重新初始化提醒框的书体属性防止从父成分世袭样式影响。 <a href='; reset-text(); font-size: $font-size-sm;

1
2
3
4
5
6
7
// Our parent element can be arbitrary since tooltips are by default inserted as a
// sibling of their target element. So reset our font and text properties to avoid
// inheriting weird values.
// 由于提示框会被默认插入到目标元素后作为一个兄弟元素,
// 所以需要重置提示框的字体属性避免从父元素继承样式影响。
<a href='http://www.jobbole.com/members/include'>@include</a> reset-text();
font-size: $font-size-sm;

这条注释很风趣,看起来有如并不背弃“表达从头到尾的经过实际不是认证效果与利益?”准则,它标记由于或然会被一些预期之外的后续字体属性影响,所以用导入的办法来重新载入参数字体属性。

但越发来看,显明在文书头导入重新设置样式的并世无双的分解就是忧郁被接二连三样式影响。

所以,我感觉这种注释也是无需的,因为导入函数名字曾经证实用项了,尽量让函数名适合营用,如reset-inherited-font或近乎的名字,不止清晰表明了用项还是印证了缘由。这么些是叁个函数调用,函数名曾经够用解释了。优先用这种办法来证实用项能够代表一些注脚。

CSS预微处理机让CSS更就好像古板一编写程语言。尽或者使用命名杰出且有含义的变量和函数,那样能让代码更清晰。

二、语法特性

不佳: 过时的批注

.dropdown-header { … white-space: nowrap; // as with > li > a }

1
2
3
4
.dropdown-header {
  …
  white-space: nowrap; // as with > li > a
}

“as with > li > a”是何许看头?小编第生机勃勃影响便是可能在文件中还会有二个> li > a的采用器,而那行代码正是指这些选拔器。恐怕文件中有大器晚成段注释会特地解释为啥这么写,但本身将文件重头到尾都看了意气风发派,开采并未有那几个选用器。文件独有多个.dropdown-item选取器下有八个nowrap属性,可能是正是指这么些?或许恐怕这段注释是指某行已经被删除的代码或引进其余文件中的代码?若想要通透到底弄精晓那些注释的功效,唯黄金时代的方式正是翻遍整个git记录了啊。

那是一个过时的疏解,恐怕它原先是有效的,但却长日子尚无利用,所以过时了。那有可能正是为啥罗Bert马丁对注释的观点:若注释对应的代码更新了讲明就没用了,以至更不佳,注释大概会将你引到错误的矛头。若觉察这么的笺注,必定要删掉。它完全没用,并且会浪费时间去思索到底有吗用?

1、变量(Variables)

变量允许大家单独定义一文山会海通用的样式,然后在急需的时候去调用。所以在做全局样式调解的时候大家只怕只必要改革几行代码就足以了。

例如:

@nice-blue: #5B83AD;
@light-blue: @nice-blue + #111;

#header {
  color: @light-blue;
}

输出:

#header {
  color: #6c94be;
}

留意:这里的变量实际上是常量。

变量也得以用来选择器名称、属性名、UCRUISERL和 @import 注明。

一时候有用的:有特异意义的笺注

日常来讲是黄金时代段带注释的代码:

.dropdown-item { display: block; width: 100%; // For `

1
2
3
.dropdown-item {
  display: block;
  width: 100%; // For `

与此相类似的注释正是实用的,它们能告诉大家,这个特定的属性是为隐讳``样式而写的。那样的讲授正是可行的,因为临时代码的用意不是那么刚烈的。

但此刻也急需问叁个难题:有哪些措施能让代码自表明呢?必要能够设想将那一个特定的质量移到第2个选项器中,特意为这一个开关设置的选择器。

.dropdown-item { display: block; padding: $dropdown-item-padding-y $dropdown-item-padding-x; clear: both; font-weight: $font-weight-normal; color: $dropdown-link-color; white-space: nowrap; } button.dropdown-item { width: 100%; text-align: inherit; background: none; border: 0; }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
.dropdown-item {
  display: block;
  padding: $dropdown-item-padding-y $dropdown-item-padding-x;
  clear: both;
  font-weight: $font-weight-normal;
  color: $dropdown-link-color;
  white-space: nowrap;
}
 
button.dropdown-item {
  width: 100%;
  text-align: inherit;
  background: none;
  border: 0;
}

如此那般就可怜明晰且轻巧了解,但副功效正是:特意扩大了三个极其的选拔器。

而相反,笔者觉着这种方法要命便于使用mixin混入格局。重构为八个函数,该函数能在其他地方定义,并且让代码更分明。思忖如下代码:

.dropdown-item { <a href='; remove-button-styles; display: block; width: 100%; padding: $dropdown-item-padding-y $dropdown-item-padding-x; clear: both; font-weight: $font-weight-normal; color: $dropdown-link-color; white-space: nowrap; }

1
2
3
4
5
6
7
8
9
10
11
.dropdown-item {
  <a href='http://www.jobbole.com/members/include'>@include</a> remove-button-styles;
 
  display: block;
  width: 100%;
  padding: $dropdown-item-padding-y $dropdown-item-padding-x;
  clear: both;
  font-weight: $font-weight-normal;
  color: $dropdown-link-color;
  white-space: nowrap;
}

这段代码未有用其余注释,但其功能很清楚,因为它接收的公用函数在此外模块也能用到。笔者将width:100%保留下来并不是移到函数中,因为若将函数混和代码时,width:100%也许会引起部分别样标题。

在自己起来察觉“代码异味(Code Smell卡塔尔国”之前,一开始.dropdown-item代码有十行,小编那多少个欣赏用mixin,mixin是叁个能大幅减弱代码行数的好东西,它能让我们飞快的掌握代码的大概用项。

纵然使用函数重构代码实际不是都那样有效,但尽只怕多用。

1卡塔尔选拔器名称

例如:

// Variables
@my-selector: banner;

// Usage
.@{my-selector} {
  font-weight: bold;
  line-height: 40px;
  margin: 0 auto;
} 

输出:

.banner {
  font-weight: bold;
  line-height: 40px;
  margin: 0 auto;
}

好:阐明难懂的补丁性的代码

本人对注释亦不是总那么苛刻的,例如小编就很难找到上面包车型大巴注明的主题材料,若你曾看过normalize.css的源码,你一定会小心到它满满的注释,不能不说,真是“极好的”注释。

赏鉴生机勃勃番:

/** * 1. Add the correct box sizing in Firefox. * FF下平常的盒子模型 * 2. Show the overflow in Edge and IE. * 在Edge和IE下overflow为visble */ hr { box-sizing: content-box; /* 1 */ height: 0; /* 1 */ overflow: visible; /* 2 */ }

1
2
3
4
5
6
7
8
9
10
11
/**
* 1. Add the correct box sizing in Firefox.
* FF下正常的盒子模型
* 2. Show the overflow in Edge and IE.
* 在Edge和IE下overflow为visble
*/
hr {
  box-sizing: content-box; /* 1 */
  height: 0; /* 1 */
  overflow: visible; /* 2 */
}

若未有那一个注释,你长久不晓得怎么如此写。修复特定浏览器bug的代码往往是猛烈难懂的,平常会被看做无用代码删掉。

鉴于Normalize库的靶子是提供二个完全风华正茂致样式遇到,所以须求广大那样的笺注。采取器都以项目和天性采用器,未有任何class名,同一时候由于不是可命名的class名,所以自文书档案特不便。

如下为另大器晚成段Bootstrap的疏解:

/* Chrome (OSX) fix for */ select { background: #fff !important; }

1
2
3
4
/* Chrome (OSX) fix for https://github.com/twbs/bootstrap/issues/11245 */
select {
  background: #fff !important;
}

五个Github链接,极度管用。固然不张开连接也能领会此时是一个bug,何况有相当大可能是三个可怜难定位的bug。若有要求,能够透过链接获取越来越多新闻。最佳的是,因为还未有大段大段的文件去解释bug,所以它并不会打乱代码逻辑,同偶尔间也告诉大家何地能够收获越来越多消息。若使用处目与事务追踪工具如JIRA,那么能够间接在解说中与号码关联起来。

本来,不是各种打补丁的代码都要这么注释,但若bug不是那么轻巧觉察,并且与浏览器怪癖有关,那么照旧那样注释吧。

2)属性名

例如:

@property: color;

.widget {
  @{property}: #0ee;
  background-@{property}: #999;
} 

输出:

.widget {
  color: #0ee;
  background-color: #999;
} 

好:指令式注释

有个别工具如KSS , 会在CSS文件中开创一些样式标准。如下:

/* Alerts An alert box requires a contextual class to specify its importance. 三个警报音讯框需求与语境有关的的类来钦命其关键 马克up:

1
2
3
4
5
6
/*
Alerts
An alert box requires a contextual class to specify its importance.
一个警告信息框需要与语境有关的的类来指定其重要性
 
Markup:

Take note of this important alert message.

alert-success - Something good or successful 好的或成功的 alert-info - Something worth noting, but not super important 不那么主要的 alert-warning - Something to note, may require attention 供给被升迁并记下,要求引起注意的 alert-danger - Something important. Usually signifies an error. 非常主要的,常用于错误 Styleguide Alerts */

1
2
3
4
5
6
7
alert-success   - Something good or successful 好的或成功的
alert-info      - Something worth noting, but not super important 不那么重要的
alert-warning   - Something to note, may require attention 需要被提示并记录,需要引起注意的
alert-danger    - Something important. Usually signifies an error. 非常重要的,常用于错误
 
Styleguide Alerts
*/

那不只是注释,这是正式,它能被KSS拆解解析并用以生成HTML。那曾经算是项目文书档案的风度翩翩有的了,何况只好说,这比手动成立多个别离的HTML文件要好过多,因为其在同叁个文本内且始终与代码相相配。

其它风华正茂种指令式注释为准许新闻,当使用第三方库并在讲明中表明许可新闻时,日常都亟需包蕴。

而自个儿贴出罗Bert Martin关于注释的话时 Robert Martin 的话 ,就像应当解释一下,但并未那么做。因为笔者认为那是一句轻松领会的话,若你还在代码中四处写注释,那么请先思忖是还是不是制造。

1 赞 收藏 评论

图片 2

3)变量名

例如:

@fnord:  "I am fnord.";
@var:    "fnord";
content: @@var;

输出:

content: "I am fnord.";

4)URL

例如:

// Variables
@images: "../img";

// Usage
body {
  color: #444;
  background: url("@{images}/white-sand.png");
} 

5卡塔 尔(英语:State of Qatar)导入注解

例如:

// Variables
@themes: "../../src/themes";

// Usage
@import "@{themes}/tidal-wave.less"; 

变量是懒加载的,不是必得在行使前证明,能够在行使后声称。例如:

.lazy-eval {
  width: @var;
}

@var: @a;
@a: 9%;

2、混合(Mixins)

掺杂可以将多个定义好的class A轻巧的引入到另叁个class B中,从而轻便达成class B世袭class A中的全数属性。我们还能带参数地调用,就疑似使用函数同样。

例如:

.bordered {
  border-top: dotted 1px black;
  border-bottom: solid 2px black;
}
#menu a {
  color: #111;
  .bordered;
}
.post a {
  color: red;
  .bordered;
}  

输出:

.bordered {
  border-top: dotted 1px black;
  border-bottom: solid 2px black;
}
#menu a {
  color: #111;
  border-top: dotted 1px black;
  border-bottom: solid 2px black;
}
.post a {
  color: red;
  border-top: dotted 1px black;
  border-bottom: solid 2px black;
}

1)不输出mixin

能够在mixin后边增添"()"括号,让其不出口。

例如:

.my-mixin {
  color: black;
}
.my-other-mixin() {
  background: white;
}
.class {
  .my-mixin;
  .my-other-mixin;
}

输出:

.my-mixin {
  color: black;
}
.class {
  color: black;
  background: white;
}

2) !important 关键字

在mixin前边使用 !important 关键字,那么继续的具有属性都会增添 !important 。

例如:

.foo (@bg: #f5f5f5, @color: #900) {
  background: @bg;
  color: @color;
}
.unimportant {
  .foo();
}
.important {
  .foo() !important;
}

输出:

.unimportant {
  background: #f5f5f5;
  color: #900;
}
.important {
  background: #f5f5f5 !important;
  color: #900 !important;
} 

3卡塔 尔(阿拉伯语:قطر‎能够传递参数的Mixins

例如:

.border-radius(@radius) {
  -webkit-border-radius: @radius;
  -moz-border-radius: @radius;
  border-radius: @radius;
}
#header {
  .border-radius(4px);
}
.button {
  .border-radius(6px);
} 

输出:

#header {
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  border-radius: 4px;
}
.button {
  -webkit-border-radius: 6px;
  -moz-border-radius: 6px;
  border-radius: 6px;
}

也足以设置参数私下认可值。举个例子:

.border-radius(@radius: 5px) {
  -webkit-border-radius: @radius;
     -moz-border-radius: @radius;
          border-radius: @radius;
}
#header {
  .border-radius;
}

输出:

header {
  -webkit-border-radius: 5px;
  -moz-border-radius: 5px;
  border-radius: 5px;
} 

3、嵌套(Nested Rules)

能够在一个接受器中嵌套另一个增选器来达成一而再再而三。

例如:

#header {
  color: black;
}
#header .navigation {
  font-size: 12px;
}
#header .logo {
  width: 300px;
}  

能够写成:

#header {
  color: black;
  .navigation {
    font-size: 12px;
  }
  .logo {
    width: 300px;
  }
}  

例如:

.clearfix {
  display: block;
  zoom: 1;

  &:after {
    content: " ";
    display: block;
    font-size: 0;
    height: 0;
    clear: both;
    visibility: hidden;
  }
} 

中间,&当前选取器的父成分。

4、运算符(Operations)

运算提供了加,减,乘,除操作;大家得以做属性值和颜色的演算,那样就可以实现属性值之间的复杂关系。

例如:

// numbers are converted into the same units
@conversion-1: 5cm + 10mm; // result is 6cm
@conversion-2: 2 - 3cm - 5mm; // result is 1.5cm

// conversion is impossible
@incompatible-units: 2 + 5px - 3cm; // result is 4px

// example with variables
@base: 5%;
@filler: @base * 2; // result is 10%
@other: @base + @filler; // result is 15%

@color: #224488 / 2; //results in #112244 
background-color: #112244 + #111; // result is #223355

5、转码(Escaping)

转码允许你使用恣意的字符串作为品质或变量值。格式: ~"anything" 或 ~'anything' 。``

例如:

.weird-element {
  content: ~"^//* some horrible but needed css hack";
}

输出:

.weird-element {
  content: ^//* some horrible but needed css hack;
}

6、函数(Functions)

Less提供了大气的函数用于转移颜色、管理字符串和数学生运动算。

例如:

@base: #f04615;
@width: 0.5;

.class {
  width: percentage(@width); // returns `50%`
  color: saturate(@base, 5%);
  background-color: spin(lighten(@base, 25%), 8);
}

输出:

.class {
  width: 50%;
  color: #f6430f;
  background-color: #f8b38d;
}

7、Namespaces adn Accessors

例如:

#bundle {
  .button {
    display: block;
    border: 1px solid black;
    background-color: grey;
    &:hover {
      background-color: white
    }
  }
}

#header a {
  color: orange;
  #bundle > .button;
}

输出:

#bundle .button {
  display: block;
  border: 1px solid black;
  background-color: grey;
}
#bundle .button:hover {
  background-color: white;
}
#header a {
  color: orange;
  display: block;
  border: 1px solid black;
  background-color: grey;
}
#header a:hover {
  background-color: white;
}

8、作用域(Scope)

例如:

@var: red;

#page {
  @var: white;
  #header {
    color: @var; // white
  }
} 

变量并不是必需在采纳前注解,举个例子:

@var: red;

#page {
  #header {
    color: @var; // white
  }
  @var: white;
} 

9、注释(Comments)

和CSS相似,扶植单行"//"和多行注释"/**/"。

例如:

/* One hell of a block
style comment! */
@var: red;

// Get in line!
@var: white; 

10、导入(Importing)

扶植导入 .css 文件,並且也支持导入 .less 文件(将导入在那之中定义的持有变量卡塔 尔(阿拉伯语:قطر‎。

例如:

@import "library"; // library.less
@import "typo.css"; 

11、扩展(Extend)

例1:

.animal {
  background-color: black;
  color: white;
}
.bear {
  &:extend(.animal);
  background-color: brown;
} 

输出:

.animal,
.bear {
  background-color: black;
  color: white;
}
.bear {
  background-color: brown;
} 

能够减小CSS的尺寸,例2:

.my-inline-block {
  display: inline-block;
  font-size: 0;
}
.thing1 {
  &:extend(.my-inline-block);
}
.thing2 {
  &:extend(.my-inline-block);
}

输出:

.my-inline-block,
.thing1,
.thing2 {
  display: inline-block;
  font-size: 0;
}

三、相关学习网址

LESS在线编辑器

法定日管教育学习网址

Bootstrap汉语网提供的上学网址

LESSCSS普通话官方网站

CSS预微机——Sass、LESS和Stylus实行

本文由技术教程发布,转载请注明来源:中哪些是好的注释,LessCss学习笔记