Welcome, Old Sport!

源代码注释样式和秘诀

by ilikecss ON 2011/12/31 13353

开发者有这么多的数据函数,变量引用,返回值,参数… …你怎么才能一一区分?我们应该开始讨论在注释格式化的一些差异,提供一些很好的建议已帮助您成为一个好的代码写手。我会提供一些具体的技巧和例子,你可以马上开始使用!

1. 单行注释

这里只是提出建议,个别编程语言并没有准则或指定设置文档规范。话虽如此,现代开发者们已经经过时间考验组合出颇具代表的代码注释规范和风格。
可以说在大多数编程语言中都存在的注释文档,很好理解,就是在程序中某一行后面加入注释来解释其意。※请在你的程序代码重点部分加入注释,多而无用。

// begin variable listing
var myvar = 1;
..

2. 块描述

每当你设置一个新功能或区分种类时,就可以在代码开始端加入块描述的注释方法。

/**
  * @desc opens a modal window to display a message
  * @param string $msg - the message to be displayed
  * @return bool - success or failure
*/
function modalPopup($msg) {
...
}

3. 类/群/声明的描述

我们经常可以在Javascript和CSS最上面看得到此类注释,往往都是说明该代码的出处,作者,联系方式,以及大致用途。在这里提倡大家如果在网上得到的代码有类似注释,请大家支持版权,请勿删除。

/**
  * @desc this class will hold functions for user interaction
  * examples include user_pass(), user_username(), user_age(), user_regdate()
  * @author Jake Rocheleau jakerocheleau@gmail.com
  * @required settings.php
*/
abstract class myWebClass { }

4. 注释在前端的运用

一个好的网站Coding体现在标签的使用,架构的清晰、规范。页面当中CSS,Javascript,Include,各个Layout的注释清楚,能给检查代码的朋友带来方便也有利于SEO。

5. CSS组群注释的运用

CSS的书写规范要靠长期养成的习惯来建立自己的独特风格,对CSS进行分类注释,这样在同时调用多个CSS时就不容易搞错,页面各个部位的分类注释等等。

@resets – taking away default browser margins, padding, fonts, colors, etc.
@fonts – paragraphs, headings, blockquotes, links, code
@navigation – the main core website navigation links
@layout – wrapper, container, sidebars
@header & @footer – these may vary based on your design. Possible styles include links and unordered lists, footer columns, headings, sub-navs
/** @group footer, small fonts, columns, external links **/

6. 语言的组织在注释中

并不是所有的开发人员都看的懂所有的编程语言,请你在注释时不要使用编程的专业语言,尽量使用口语,这样在其他人查看你的代码时也可以大致了解了。

7. 注释的空间

在注释时,请不要挤得密密麻麻,上下可以以空一行为间距的来划分种类,以便阅读。

$dir1 = "/home/";                 // set main home directory
$myCurrentDir = getCurDirr();     // set the current user directory
$userVar = $get_username();      // current user's username

8. 错误的检查

source code comment styling and tips

当完成一个页面时,请在检查完浏览器的兼容同时也把您所写的注释检查一遍,错别字、语句组织等,细节体现整体。

如果你是一个精益求精的设计开发者,我想注释对你来说也是一门必须融会贯通的学问。

目前还没有评论



TOP