前言

  • 首先这个文档中主要记述了自己在编写html代码时如何构建良好的dom结构的一些所思所想,在这一部分主要说明按“块”构建dom结构的思路。同时在这篇文档中也记述了自己对代码注释的理解,在这一部分主要说明注释对理解代码结构的重要性和提高团队配合的重要性出发来说明,因为之前有一段时间的工作属于在“一直修改和维护别人代码”或者说把别人项目的其中一部分独立开来成为一个项目,在这个过程中我渐渐对代码注释的重要性是深有体会的!

  • 当然了,这些可能是我自己的理解,并不是最优的,所以没必要在自己的项目开发过程中按照这些方式做。你可以根据你项目的实际情况或者更利于你的当前团队既有的模式具体分析来决定怎么做,但是我们的目的————形成良好的代码结构,便于后期维护,以及团队协作。不要以为代码随便写没关系,后期维护起来你就知道“后果”了。

按“块”的结构构建你的的dom代码

  • 首先说一下我最开始写html代码的时候怎么构建dom的,那时候的想法就是总的页面用一个div来包住,从而实现所有的初始化样式或者说重置样式都在div上设置了,以为可以这样省下很多重复的css代码,其实并不是这回事,如果这样写的话,那么你的代码将会很将会很僵化,非常不灵活,所以后期我发现不能这样写dom结构,为什么呢!我们来设想这样一种场景:板块1和板块2是页面中两块不同的内容,板块1左右边距有个10px的外边距,而板块2没有边距,而是贴边的。如果用一个div来把这两块内容包住,然后在div上设置padding:0px 10px来实现左右的外边距,对于板块1来说,确实不用写margin来实现外边距了,可是对于板块2呢!这是我们只能通过margin等于负值来实现贴边展现效果,好像貌似这样实现了确实能达到效果,但是我们这里只是举了一个简单例子,如果是更复杂的生产环境中呢!不到不得已尽量不要使用负margin,因为页面负值之后你将很难管理你的页面样式。此外,我还发现一个问题,如果采用这样的dom结构,页面将会变得很难维护,比如你将来在这个div之内又加一些子板块内容,如果此时需要设置一些冲突的样式的话,那么就会在父div上或新div上设置一些冗余样式来兼容,这样你将变得头都大了!当然采用这样的布局方式还有其他很多问题,后面将一一说明!

  • 那我是怎么布局的呢?我们还是从得到一张设计图开始吧,假设设计图如下:

05. 写html代码时按“块”的方式写dom的优势以及代码注释的重要性 - 图1

我们分析一下页面结构,设计图顶部出现的是一个固定在顶部的搜索栏,中间是我们理解为产品内容区域,而底部是一个固定的网站导航栏,那么从现在开始,你的脑海应该呈现这样的一副按“块”分的设计图结构,然后分块完成之!如下图:

05. 写html代码时按“块”的方式写dom的优势以及代码注释的重要性 - 图2

好了,现在每个块的内容或者样式都可以分开写了,这样就不会担心彼此互相影响了,那么怎么解决刚才那种布局中会出现的css代码冗余呢,比如这里如果三个块都有一个左右10px的margin,我只需要把这部分提炼出来单独用一个css类来表示,比如:

  1. outside-margin:{
  2. margin:0px 10px;
  3. }

这样在每个板块用一下这个类就不会写重复的样式了!而板块之间都不影响了,并不影响将来扩展或删减,也不至于项目越来越到,你却摸不着头脑了!

  • 虽然按“块”的结构构建你的dom结构,只是很微不足道的优化,但是我确认为它带来了以下优点:

你的代码彼此耦合性降低,利于将来某个时候扩展或删减;

良好的代码结构,集合我后面将要讲到的注释,你将很容易维护你的代码,别人也能方便对你的代码有个清晰认识;

便于你腾出时间专注于某个点工作,我想这肯定会提升你的工作质量的。

必须使用注释

  • 首先为什么要强调必须呢!因为曾经自己有一段时间一直在维护别人前期已经搭建好的项目结构,所以那个时候才能理解为什么注释这么重要,首先来一张我曾经修改别人html代码结构模板图;

05. 写html代码时按“块”的方式写dom的优势以及代码注释的重要性 - 图3

我们可以发现完全没有注释,我们要找到bug的地方不费点力气,我想是很难找到的,所以良好的注释在团队合作中真的很重要。

  • 当然我第一次喜欢上注释也并非是为了团队合作,因为之前前端我一个人在做,所以谈合作有些牵强,也不是没合作,但大部分时间自己在维护自己写的代码。所以我第一次迷恋上写注释是因为自己强迫症,总觉得那样写出来具有良好的代码结构,到了后面,发现确实注释能给工作带来很多便利之处。至少发现bug到修复bug完成不会像之前时间花费的多了,而且很容易找到出现问题的地方。

  • 下面我说一下,在工作开发过程中我怎样采用注释的。需要提前说明一下的是,在团队开发过程中,注释是很好的便于团队合作,所以未必我下面说的注释就是最好的,你当前使用的注释结构也不一定是差的,总的看团队合作模式,大家已经有了稳定的约定俗成的注释模式,那么就保持这种风格就好!

html注释

  • 因为本身html是标记性语言,有开始标签和结束标签,那么我也采用类似的注释结构,将每个块开始处和结束处都加上一个标记,以表明这部分代码表现是页面那部分内容。如下:
  1. <!--板块1 start-->
  2. <div>
  3. contents go here.
  4. .
  5. .
  6. .
  7. </div>
  8. <!--板块1 end-->

我觉得写注释跟前面按“块”的方式构建你的dom相得益彰,有异曲同工之妙,都能很好的表述你的代码结构,好的注释解释更能很好的说明这部分html实现的内容!

css注释

  • 对于css代码注释,我的理解就是你需要说明你的样式用于那部分内容,或者实现什么组件样式。所以采用两种方式来实现对css代码进行注释。如下:
  1. /*第一种注释 用于表示实现了页面那部分html代码的样式*/
  2. /*
  3. ***this css is used in the user survey
  4. */
  5. .class1{
  6. ....
  7. }
  8. .class2{
  9. ....
  10. }
  11. .
  12. .
  13. .
  14. /*第二种注释 用于实现什么组件的样式*/
  15. /*
  16. ***this style is for a button
  17. */
  18. .btn{
  19. padding:0.3em 1.2em;
  20. -webkit-borde-radius:3px;
  21. background-color:#c00;
  22. color:#fff;
  23. outline:none;
  24. border:0px;
  25. font:inherit;
  26. }

当然了,现在提供了sass和less等css预编译语言,它们的注释我也是采用类似注释结构。这种注释结构能很清楚css代码用于那部分内容和实现了什么样式。

javascript注释

  • 我觉得js注释还是需要讲究的,因为曾经写过一种类型的样式,但是后面觉得不适合,看一下我最开始的写的js注释代码:
  1. (function(){
  2. //a表示当前是否当前正在获取服务器数据
  3. //b表示服务器数据已经拉取完成没有数据可以获取
  4. //num用来初始一个获取数据计时器
  5. var a = false,b = true,num = 1;
  6. function getData(){
  7. //代码省略
  8. };
  9. })();

首先说一下这种代码注释的注重点,实现给每个变量的用途添加说明,其实这是完全没有必要的,因为如果这样注释的话,我想你的代码中肯定会有很多这样的冗余注释,其实我们后期维护代码的过程中并不是特别需要了解每个变量的意义,而是需要快速定位出现问题的代码所在的地方。至于变量所代表的的含义,即时你告诉了维护的同事,他也需要重新看一下你写的代码才能知道问题所在,而他在看代码的过程中,他就已经知道你的变量含义了,所以对变量含义进行注释是没有必要的!

  • 所以我对于js采用类似如下的注释结构,可以借鉴一下:
  1. /**
  2. ** 这部分脚本用于实现向服务器拉取banner图数据
  3. **/
  4. (function getBannerData(){
  5. //代码逻辑省略
  6. })();
  7. /**
  8. ** 这部分代码用于实现用户登陆逻辑
  9. **/
  10. (function userLogin(){
  11. //代码逻辑省略
  12. })();
  13. //等等都这样注释下去

我发现上面的js注释方式能够很快帮你定位到出现问题的代码,并且很好的管理的代码结构,所以我一直在用!

内容持续修改中….