在绝大多数现代语言中，我们越来越注意源代码的版面和样式，而在绝大多数现代的编辑器中，我们都有了可以依赖的插件，进行版式编排。
糟糕的排版会带来很多问题，比如下面这个:
<script type="text/javascript">
var func = function(msg){
if (msg) console.log('I\'m Exit!');
return function(){console.log('msg')};
}
func('body')
</script>
当然，你会说，这种都是经验问题，踩过一个坑，就知道会执行到哪里了。
这个回答不需要反驳，但是你同样无法反驳：原来应该注意的细节被转移了，时间和精力被无辜浪费了，程序中的实际代码应该是可维护的，友好的，不是么。
如果要讨论每个细节的话，我们恐怕要坐一起面对面，讨论个三天三夜….那应该也不足以讨论完所有的细节，所以就注释，来简单的说一下我个人的看法吧。
代码注释是修建程序大厦中的锦上添花，而并非构建基础结构的基石，他只是提供对一个细节的额外指向和补充，并非完整的参考，如API文档，也并非规范内容。而且作为代码的贴身保镖，如果你的函数出现问题，那么首先应该被阅读到的就是注释。
重构时常常遇到这样的代码：
<?php
if (condition) {
}else{
//code...
}
?>
原作者在修筑的时候，肯定想到了什么，但是因为不是主要的功能，或者想后续完成，于是把第一个选择分支置空了，这时，或许应该在wiki或者这段分支中添加一点注释，告诉后人，这个版本先不需要这个功能，咱们下个版本添加。
否则在文档从几十行到几十kb/上百kb的时候，这个细节如果没有记录，或许早已被人忘记，而这些全部都是良性程序架构的潜在敌人。
我们常常在写文档的时候，就纠结于，我们该弄个多华丽的文档说明开头呢。
<!-- _____ ____ __ ____ _______________ ______ __
/ ___// __ \/ / / / / /_ __/ ____/ | / __ \ \/ /
\__ \/ / / / / / / / / / / __/ / /| | / /_/ /\ /
___/ / /_/ / /_/ / /___/ / / /___/ ___ |/ _, _/ / /
/____/\____/\____/_____/_/ /_____/_/ |_/_/ |_| /_/
-->
一个ASCII艺术字，或者字符画一个鸟叔和欧巴刚那死大？看起来很绚丽，但是你需要这些注释帮你执行什么华丽或者伟大的壮举么？
显而易见的，他们只是注释，很多语言在执行编译的时候是抛弃注释的，比如C，当然也有很多语言的某些编译方式的选择不同，会在编译之后保留注释，比如VB。他们不是关键的组成成分，但是是必要的。
千万不要把时间耗费在大量不需要维护的注释上。
注释应该是高质量，而不是高数量的，就HTML结构来说，因为它看起来比较直观和简单。 因为在模版中，我们的HTML比想象中看起来要碎一点，原本是这样的结构：
<body>
<div class="header"></div>
<div class="wrap"></div>
<div class="footer"></div>
</body>
可能会变成这样
<body>
<div class="header">
<div class="logo"></div>
<div class="search"></div>
<ul class="nav">
<li class="nav-item"></li>
<li class="nav-item"></li>
<li class="nav-item"></li>
</ul>
</div>
<div class="wrap">
<div class="side"></div>
<div class="main">
<div class="left"></div>
<div class="right"></div>
</div>
</div>
<div class="footer">
<div class="links"></div>
<div class="tags"></div>
<div class="contact"></div>
</div>
</body>
如果你知道你的结构可能变的很复杂，那么为什么不在建构之初这么写呢？
<body>
<!-- 头部:开始 -->
<div class="header"></div>
<!-- 头部:结束 -->
<!-- 内容:开始 -->
<div class="wrap"></div>
<!-- 内容:结束 -->
<!-- 尾部:开始 -->
<div class="footer"></div>
<!-- 尾部:结束 -->
</body>
看起来注释是实际内容比重的6/11 ，但是他为以后的扩展提供了良好的指向。
但是相比较的这种注释就不友好了。
<body>
<!-- 头部开始 -->
<div class="header">
<div class="logo">
<!-- logo模块 -->
<!-- 为了SEO，我们这里使用H1，文档之后不要再出现H1 -->
<!-- 不考虑无CSS时候的样式，使用CSS来展示LOGO -->
<h1><a href="#">logo</a></h1>
</div>
<!-- logo模块end -->
<div class="this_div_is_search_box">
<!-- 这个div是放搜索模块的 -->
<input type="text" value="search">
<!-- 这个要支持placeholder，但是不要用placeholder属性，要使用js，向下兼容，blabla -->
<input type="button" value="do it~">
<!-- 这个button要不要用a代替呢，反正没form -->
</div>
<!-- 搜索区域结束 -->
</div>
<!-- 头部结束 -->
</body>
如果你看完这段，觉得没有什么，那么我觉得你没有必要再接着看下去了。
这段结构充满非友好的书写，命名随意不统一，控件标签使用不规范，注释简直就是心理直白，或者说和代码之间的感情直播。
注释被滥用了，数量上和内容上，其实只需要把可能被程序填充，里面会出现大量结构的出入口写上范围注释，以及本段功能待定，出于SEO考虑，出于优雅降级考虑即可。写的人文艺，看的人舒心，而且还能解决问题。
一首曲子好听，不在于它是几个小时的歌剧，而关乎于它的旋律，优美的旋律，十几秒足以打动人心。
<script type="text/javascript">
var action = function(){
if (true) {
doA();//用A过程再次干嘛干嘛
}else{
doB();//doB()..执行B过程。
}
}
</script>
这里的注释同样让人拙急，我们阅读至此，很大概率会跟下去看看这个函数是干嘛的，除非我们约定了强命名，以及我们很熟悉这个函数的具体实现。
而且在代码中重复注释是一件很不文艺&&很不普通的错误。
或许这么写会好点。
<script type="text/javascript">
var action = function(){
//数据来源正确
if (true) {
doA();
}else{
doB();//显示提示用户信息，此处待完善
}
}
</script>
我觉得注释应该实事求是和不扭曲事实，如果不确定，咱们就不确定就可以了。
<script type="text/javascript">
var switcher = true;
switcher = false
一堆过程之后，函数跑到下面
// 程序开关是打开的
if (switcher) {
// 我们期望的理想达成了！
doA();
}
doB();//必须执行A之后执行B
</script>
上面这段代码很容易把一个老实巴交的程序员带入万劫不复，如果这个是核心业务逻辑的话。
如果两个程序员关系很好，或者一时疏忽，很容易相信注释，或者是那个程序员自己查阅自己以前的注释，觉得是对的。
然后…我想就没有然后了…
<script type="text/javascript">
var doA = function(){
程序A具备检查字符串合法的功能
}
var switcher = true;
switcher = false
if (switcher) {
// 猴年马月，程序A没有做合法性判断，需要添加
checkIt();//新添加的检查函数。by xyz
doA();
}else{
doB();
}
</script>
这样的苦逼事情，我们经常遇到，为什么呢，一个是一时大意，没有实事求是的检查每一段代码，再一个就是注释的错误指向。
猴年马月的东西，没有在维护的时候被删除，于是…举个更夸张的例子，但是效果应该会很好。
<script type="text/javascript">
var doA = function(){
核心逻辑业务，被其他逻辑严重依赖，不容有闪失！
//add 一个功能 猴年马月
//add 一个功能 猴年马月+1
//add 一个功能 猴年马月+2
//add 一个功能 猴年马月+3
//add 一个功能 猴年马月+4
//add 一个功能 猴年马月+5
//add 一个功能 猴年马月+6
//add 一个功能 猴年马月+7
}
</script>
你看过之后是不是想说，原来网易和迅雷社区里的盖楼，咱们程序里也有啊-，- 有句话说的很好，过去的事情，就让他过去吧。
我们来看看一个头疼的事情
<body>
<body class="single single-post postid-3006 single-format-standard custom-background">
<div id="wrap">
<header id="header">
<h1 id="sitetitle"><a href="#">11122</a></h1>
<nav id="mainnav">
<!-- <div class="menu"><ul><li ><a href="#" title="Home">Home</a></li><li class="page_item page-item-61"><a href="#about/">About</a></li></ul></div>
<form role="search" action="#">
<label class="assistive-text" for="searchbox">Search for:</label>
<input id="searchbox" name="s" type=text placeholder="Search..." value="">
<input class="button" type=submit value="Search">
</form> -->
</nav>
</header>
<div id="main">
这种大段不用的代码，常常在程序员考古的时候发现，某些项目临时上线，也会在页面中看到这个东西。
这个东西和之前上面说的问题是一致的，只会让后面的同事越来越迷惑，甚至保持和这个一致的习惯，就是把不用的东西防止代码中，
增加复杂度和文档大小。
如果你反驳我，这个以后可以用，好吧，我的看法是，你有git，svn呢，咱们可以记录版本的，干干净净的多好~
如果你留下这些，难免在修改的时候分心，也不利于代码编写。
人各有志，啊不是，是魔术人人会变，人人技法不同，不需要苛求细节？
真的是这个样子么？我们来看一个小细节：
<script type="text/javascript">
var doA = function(){
//todo 说明
//TODO: DO SOMETHING
}
</script>
如果你要查找所有的todo，那么使用///TODO[ |:]/i搜索和使用//TODO:搜索的代价也是不同的。 当然，技术大牛或者正则着迷者可以无视这个事情，如果您真的觉得没有必要统一。
说了这么多，谈谈注释的排版吧
单行注释并非只可以使用//，如下：
<script type="text/javascript">
/* 注释内容 */
/*----- 注释内容 ------*/
/*========== 注释内容 ==========*/
// 注释内容
</script>
常见的块级注释
<script type="text/javascript">
/**
TODO:
- 第一件事情
- 第二件事情
**/
/*========================
= 注释内容 =
========================*/
/**
*
* 注释内容
*
**/
</script>
当然，有人建议注释也保持级别如这样： 我觉得这样只是浪费了程序员的精力，去关注收益比较低的事情。
<!-- !注释内容 -->
<!-- !!注释内容 -->
<!-- !!!注释内容 -->
<!-- @@@注释内容 -->
<!-- @@注释内容 -->
<!-- @注释内容 -->
不过成对出现的东西，某些时候出现还是很有必要以及很直观的。
<script type="text/javascript">
/*----- Start of Post Content ------*/
/*----- End of Post Content ------*/
/*========== 程序：开始 ==========*/
/*========== 程序：结束 ==========*/
//===!开始
//===@结束
</script>
吐槽一下：其实本来只是想分享一下简单的注释的样式和排版，木有想到又是一篇洋洋洒洒的流水账-，-
欢迎留言讨论，共同进步。