闲话注释风格

《一个码农的自我修养》一书花了相当多的篇幅来阐述代码注释的重要性,可见注释真的很重要!好吧,其实没这本书~

不过,应该没人能质疑注释的重要性,因为没多少人愿意接手和维护一堆纯粹的逻辑符号,虽然个人项目另当别论,但不是每个人的记忆力都能突破天际地记得“原来我曾经写过这样的代码”。所以,我个人对那些写了一堆代码没一句注释的伪牛人是嗤之以鼻的。但写这篇文章的自己可能也是相当的小题大做,其实注释只要是简明清楚,都应该来者不拒,而没必要太注重形式。一个团队还是保持某一种统一的风格比较好,在大框架下的求同存异,每个人也都应该保留适合自己的空间。

本文旨在罗列一些笔者遇到的注释,仅仅只是闲谈。每个人都有适合自己的风格,无所谓好坏。

无论是C风格的注释,还是后来C++增加的单行注释,我们都再熟悉不过了:

/* Basic Comment */
// Basic Comment

但个人而言,单行注释我更多地是用在调试上,我几乎不用单行注释来写注释。单行注释常常被用在画框上,但个人感觉太粗,影响视觉。而且真正的注释和调试代码最好在视觉上分开,所以我几乎不用,以至于到后来看到自己顺手写的单行注释会非常别扭,出于一种强迫下重新改回C语言的那种风格。

///////////////////////////////////////
//
//
// This is a comment hat
//
//
///////////////////////////////////////
function swordair(){}

///////////////////////////////////////
// This is a comment hat
function swordair(){}

所以本文中的单行注释,只是一笔路过。更重要的原因是,CSS里无法使用——虽然很多人提出在CSS里支持单行注释,但直到现在也没有结果。原因很简单,因为CSS里经常出现 http:// 这样的字符串,解释器需要做额外区分。而且即使浏览器支持了,当前的众多CSS格式化工具和压缩器也都需要改进算法,所以CSS的单行注释还是遥遥无期的事情。所以,即使从统一性角度看,似乎也应该选择最为古老的注释方式 /**/

除了最为常见的单行 /× comment ×/ 以外,下面这种多行的块形注释也是比较常见,特别是在Java里。这种注释方式对于函数,类,以及文档都非常有效,因为它提供了足够多的信息量:

/*
 * Group comment block.
 * Ideal for multi-line explanations and documentation.
 */

另一种较为常见的注释类似于一个大标题,非常醒目,类似于HTML里 h1 的效果:

/*------------------------------------*\
   COMMENT CONTENTS
\*------------------------------------*/
function swordair(){}

当然,如果觉得这样的标题太大,也完全可以用小一些的标题,甚至组合大小标题达到层次的效果。常见的小标题格式可能是下面这样的:

/* common */
/* --------------------------------------------- */
function swordair(){}
/* --------------------------------------------- */
/* Generic Table
---------------------------------------------------------- */
function swordair(){}

也有人喜欢用等号代替减号,这样的标题视觉上更加突出。而且长度上的不同也可以用作层次的划分。

/* ==========================================================================
   Section comment block
   ========================================================================== */

/* Sub-section comment block
   ========================================================================== */

大部分的注释就是由 /**/ 配合星号* / 减号- / **等号=**组合起来划分区域的。因为这些字符足够简单,能制造边框效应。只要你愿意,完全可以在这些条条框框里留下任何你喜欢的信息:

/*SwordAir*/
/***********************************************************
 *                                                         *
 *    ***                          *     *                 *
 *   *                             *    * *    *           *
 *    *                            *   *   *               *
 *     *  *   *   *  ***  ** *** ***   *   *   *  ** ***   *
 *      *  *  **  * *   *  **   *  *  *******  *   **      *
 *       *  **  **  *   *  *    *  *  *     *  *   *       *
 *   ****   *   *    ***   *     ** * *     *  *   *       *
 *                                                         *
 ***********************************************************/

嘛~献丑,其实我知道自己的代码画非常难看~希望有一天能稍微拿的出手一些:)

实际上,还有更多字符可以参与到注释中来,而且它们的效果显而易见。在没有任何说明的情况下,任何人都能一看就明白:

/*↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓*/
function swordair(){}
/*↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑*/

混合文字和箭头的方式也算是挺常见的,而且往往效果很好。你能很直观的看到代码从哪里开始到哪里结束。

/* ↓↓↓ Function Start ↓↓↓ */
function swordair(){}
/* ↑↑↑ Function End ↑↑↑ */

不只是箭头,三角形也表示一种同样的意思:

/* ▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼ */
function swordair(){}
/* ▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲ */

其他字符也一样。当然箭头和三角都是比较常见的,之所以常见,也是有原因的。其一是因为直观,其二,其他的一些字符可能在编辑器里乱码,这样反而让代码混乱。如果是用win7或者如aptana,遇到乱码的情况要少很多。但在winXP下,notepad++在等宽字体的配置下也只能很好地显示几种,箭头和三角都是其中之一。

不过,在网页上,它们的显示完全不成问题。它们可以说是代码注释里的非主流。

/* ☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰ */

/* ✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓ */

/* ✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗✗ */

好吧,最后这几个,连非主流都算不上,其实完全没人用~ Just For Fun!