obert C. Martin写的《Clean Code》是我读过的最好的编程书籍之一,若没有读过,推荐你将它加入书单。
注释就意味着代码无法自说明 —— Robert C. Martin
Martin在文中详细讨论了代码注释,我不会完全重复他的话。简而言之,他的意思就是,这些注释是注定会过时的。程序执行时会忽视注释,所以无法保证这些说明注释会准确的描述代码作用。所以最好的方式是让代码自说明,如此,按照代码逻辑,程序员和程序获取到的信息是一致的。
思考如下代码:
// Check to see if the employee is eligible for full benefits// 检查员工是否有资格获取全部福利if ((employee.flags & HOURLY_FLAG) && (employee.age > 65)) { …}
注释有用么?当然有用,但下面的方式可能更好:
if (employee.isEligibleForFullBenefits()) { …}
代码需要“言行一致”,注释是能够被命名良好的函数或变量取代的。Martin的意思并不是说永不使用注释,而是应该尽量避免写注释,注释就意味着代码无法自说明。
那么对CSS而言呢?
我非常赞同Martin关于注释的看法。当涉及到声明式的语言如CSS时,就发现了一些有趣的地方。声明式语言式必须符合对应格式的,而CSS选择器基本是由HTML结构决定的。对这种代码结构,我们能做的不多,这是否意味着CSS代码必须注释满天飞?
额,也许吧。有很多的理由使用注释,且注释的写法也有很多。让我们来看一些注释,思考这些注释是否应该添加。先从答案显然的开始吧,然后一步步深入到不那么好判断的。
不好:多此一举的注释
任何语言,多此一举的注释都是多余的,如下的示例出自Bootstrap3的早期版本:
// Addressesaddress {…}
显然,address是关于地址的选择器
// Unordered and Ordered listsul,ol {…}
还有?
// Blockquotesblockquote {…}
赶紧停!
千万不要写那种注释,赶紧删掉这些多余的东西,它仅仅是在重复代码而已。当然,新版本的Bootstrap已经删除掉大部分多此一举的无用注释了。
不好: 块分隔注释
对CSS而言,块分隔注释是非常特殊的,如下:
/* ----------------- * TOOLTIPS * ----------------- */
这种注释能把我逼疯。我能想到为什么会写下这种注释:有时候我们的CSS会写得非常长,当在超过千行的文件内查找时,就需要这种带特殊标志的注释来帮助快速搜索。
但事实上,很长很长的CSS文件已经不再流行了。若你的项目确实需要这种很大的CSS文件,它应该是由多个小的部分,通过CSS预处理工具组合而成的。
不好:解释语法
又要用Bootstrap举例了,以下代码出自 _tooltips.scss:
// Allow breaking very long words so they don't overflow the tooltip's bounds// 设置长单词换行word-wrap: break-word;
这种方式和“多此一举的注释”类似,注释解释word-wrap属性的作用。这里有一篇文章讲到这种注释为什么不需要的原因,注释应该解释“为什么”,而不是“是什么”,即说明原因而不是说明作用(Why, not what)。
此处有一个例外,由于CSS有很多属性,也许有些属性是你完全不知道的,那么你用这种注释是正常的。
不好:对库进行介绍
如下是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.// 由于提示框会被默认插入到目标元素后作为一个兄弟元素,// 所以需要重置提示框的字体属性避免从父元素继承样式影响。@include reset-text();font-size: $font-size-sm;
这条注释很有意思,看起来似乎并不违反“说明原因而不是说明作用?”规则,它表明由于可能会被一些意料之外的继承字体属性影响,所以用导入的方式来重置字体属性。
但进一步来看,显然在文件头导入重置样式的唯一的解释就是担心被继承样式影响。
所以,我认为这种注释也是不需要的,因为导入函数名字已经说明用途了,尽量让函数名切合作用,如reset-inherited-font或类似的名字,不仅清晰说明了用途还是说明了原因。这个是一个函数调用,函数名已经足够解释了。优先用这种方式来说明用途可以替代一些注释。
CSS预处理器让CSS更接近传统编程语言。尽可能使用命名良好且有意义的变量和函数,这样能让代码更清晰。
不好: 过时的注释
.dropdown-header { … white-space: nowrap; // as with > li > a}
“as with > li > a”是什么意思?我第一反应就是也许在文件中还有一个> li > a的选择器,而这行代码就是指那个选择器。也许文件中有一段注释会专门解释为何这样写,但我将文件重头到尾都看了一边,发现并没有这个选择器。文件只有一个.dropdown-item选择器下有一个nowrap属性,也许是就是指这个?或者也许这段注释是指某行已经被删除的代码或引入其他文件中的代码?若想要彻底弄清楚这个注释的作用,唯一的方法就是翻遍整个git记录了吧。
这是一个过时的注释,也许它以前是有用的,但却长时间没有用到,所以过时了。这也许就是为什么Robert Martin对注释的看法:若注释对应的代码更新了注释就没用了,甚至更糟糕,注释可能会将你引到错误的方向。若发现这样的注释,一定要删掉。它完全没用,而且会浪费时间去思考到底有啥用?
有时有用的:有特殊意义的注释
如下是一段带注释的代码:
.dropdown-item { display: block; width: 100%; // For `<button>`s padding: $dropdown-item-padding-y $dropdown-item-padding-x; clear: both; font-weight: $font-weight-normal; color: $dropdown-link-color; text-align: inherit; // For `<button>`s white-space: nowrap; background: none; // For `<button>`s border: 0; // For `<button>`s}
这样的注释就是有用的,它们能告诉我们,这些特定的属性是为覆盖<button>样式而写的。这样的注释就是有用的,因为有时候代码的意图不是那么显而易见的。
但此时也需要问一个问题:有什么办法能让代码自说明呢?需要可以考虑将这些特定的属性移到第二个选择器中,专门为这些按钮设置的选择器。
.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 { @include 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是一个能极大减少代码行数的好东西,它能让我们快速的知道代码的大致用途。
虽然使用函数重构代码并不是都这样有效,但尽量多用。
好:注解难懂的补丁性的代码
我对注释也不是总那么苛刻的,比如我就很难找到下面的注释的问题,若你曾看过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 */}
若没有这些注释,你永远不知道为何这样写。修复特定浏览器bug的代码往往是晦涩难懂的,常常会被当做无用代码删掉。
由于Normalize库的目标是提供一个完全一致样式环境,所以需要很多这样的注释。选择器都是类型和属性选择器,没有任何class名,同时由于不是可命名的class名,所以自文档非常困难。
如下为另一段Bootstrap的注释:
/* Chrome (OSX) fix for https://github.com/twbs/bootstrap/issues/11245 */select { background: #fff !important;}
一个Github链接,非常有用。即使不打开连接也能知道这儿是一个bug,而且有可能是一个非常难定位的bug。若有需要,可以通过链接获取更多信息。最棒的是,因为没有大段大段的文本去解释bug,所以它并不会打乱代码逻辑,同时也告诉我们哪里可以获取更多信息。若使用项目与事务跟踪工具如JIRA,那么可以直接在注释中与编号关联起来。
当然,不是每个打补丁的代码都要这样注释,但若bug不是那么容易发现,而且与浏览器怪癖有关,那么还是这样注释吧。
好:指令式注释
一些工具如KSS , 会在CSS文件中创建一些样式规范。如下:
/* Alerts An alert box requires a contextual class to specify its importance. 一个警告信息框需要与语境有关的的类来指定其重要性 Markup: <div> Take note of this important alert message. </div> 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文件要好很多,因为其在同一个文件内且始终与代码相匹配。
另外一种指令式注释为许可信息,当使用第三方库并在注释中注明许可信息时,一般都需要包含。
而我贴出Robert Martin关于注释的话时,似乎应该解释一下,但我没有那么做。因为我认为这是一句容易理解的话,若你还在代码中到处写注释,那么请先思考是否合理。
英文:Keith J. Grant 译文:众成翻译/KING
zcfy.cc/article/thoughts-on-self-documenting-css
本文摘自互联网,如有侵权,请与小编联系进行删除
Java编程中,注释是一种重要的语法元素,允许开发者在代码中添加描述性信息,而不会影响代码的执行。注释对于理解代码的逻辑、功能以及维护代码都起着至关重要的作用。Java支持三种类型的注释,分别是单行注释、多行注释和文档注释。
单行注释用于解释或描述代码中的某一行或某一部分。以双斜杠(//)开头,直到该行结束。Java编译器会忽略单行注释及其后面的所有内容。
例如:
// 这是一个单行注释
int a = 5; // 声明一个整数变量a并赋值为5
在上面的代码中,第一行是一个单独的单行注释,而第二行中的注释则紧跟在代码后面,用于解释该行代码的作用。
多行注释用于解释或描述代码中的多行内容。它以(/*)开头,以(*/)结束。Java编译器会忽略这两个符号之间的所有内容。
例如:
/*
这是一个多行注释,
可以跨越多行来解释或描述代码的功能和逻辑。
*/
int b = 10;
int c = b * 2;
在上面的代码中,多行注释用于解释接下来的两行代码的作用。
文档注释是一种特殊的多行注释,它以“/**”开头,以“*/”结束。主要用于生成API文档,帮助开发者了解和使用类或方法。JavaDoc工具可以从源代码中提取文档注释,并生成HTML格式的API文档。
文档注释中可以包含一些特殊的标签,如@author(作者)、@version(版本)、@param(参数说明)、@return(返回值说明)、@throws(抛出异常说明)等。
例如:
/**
* 这是一个文档注释的示例
*
* @author 张三
* @version 1.0
*/
public class MyClass {
/**
* 计算两个数的和
*
* @param a 第一个加数
* @param b 第二个加数
* @return 两个数的和
*/
public int sum(int a, int b) {
return a + b;
}
}
在上面的代码中,我们使用了文档注释来描述类和方法的功能、作者和版本等信息。这些信息可以通过JavaDoc工具提取并生成API文档。
注释是Java编程中不可或缺的一部分,能够帮助我们更好地理解代码,提高代码的可读性和可维护性。掌握并合理使用注释,是成为一名优秀Java开发者的必备技能之一。
.什么是HTML
HTML 是用来描述网页的一种语言。HTML 指的是超文本标记语言: HyperText Markup LanguageHTML 不是一种编程语言,而是一种标记语言标记语言是一套标记标签 (markup tag)HTML 使用标记标签来描述网页HTML 文档包含了HTML 标签及文本内容HTML文档也叫做 web 页面
二.HTML基本语法
(1)HTML标签
整个网页是从<html>这里开始的,然后到</html>结束。
(2)head标签
head标签代表页面的“头”,定义一些特殊内容,这些内容往往都是“不可见内容”(在浏览器不可见)。
(3)body标签
body标签代表页面的“身”,定义网页展示内容,这些内容往往都是可见内容(在浏览器可见)。后续课程讲解的标签都是在body标签内部的各种标签。
三.HTML语法规范
HTML中不区分大小写,但是我们一般都使用小写
HTML中的注释不能嵌套、
HTML标签必须结构完整,要么成对出现,要么自结束标签
HTML标签可以嵌套,但是不能交叉嵌套
HTML标签中的属性必须有值,且值必须加引号(双引号单引号都可以)
四.HTML标签使用方法
(1)HTML无序列表
无序列表是一个项目的列表,此列项目使用粗体圆点(典型的小黑圆圈)进行标记。
(2)有序列表
同样,有序列表也是一列项目,列表项目使用数字进行标记。 列表项使用数字来标记。
(3)段落与文字标签
(4)文本格式化标签
五.HTML表单和输入
表单是一个包含表单元素的区域。表单元素是允许用户在表单中输入内容,比如:文本域(textarea)、下拉列表、单选框(radio-buttons)、复选框(checkboxes)等等。表单使用表单标签来设置。
(1)文本域(Text Fields)
输入类型是由类型属性(type)定义的。大多数经常被用到的输入类型如下:
(2)密码字段
密码字段通过标签 来定义:
(3)单选按钮
标签定义了表单单选框选项
(4)复选框
定义了复选框. 用户需要从若干给定的选择中选取一个或若干选项。
(5)提交按钮
定义了提交按钮。当用户单击确认按钮时,表单的内容会被传送到另一个文件。表单的动作属性定义了目的文件的文件名。由动作属性定义的这个文件通常会对接收到的输入数据进行相关的处理
今天我们就先分享到这里,有不懂的可以私信我
(私信我有免费的IT课程可以领取哟)
*请认真填写需求信息,我们会在24小时内与您取得联系。