一、HTML的注释方法
<!-- html注释:START -->
内容
<!-- html注释:END -->
二、CSS的注释方法
<style type="text/css">
/* css注释*/
</style>
在单独的css样式表文件中也采用此方法注释
三、JS的注释方法
<script type="text/javascript">
//js注释
</script>
四、ASP的注释方法
<%
Set xml=Server.CreateObject("Microsoft.XMLDOM")
Set Fs=xml.documentElement.childNodes
'ASP注释
%>
其他注释方法:
比如vbs用 '注释 或 REM 注释内容
PHP支持C,C++和Unix风格的注释方式:
/* C,C++风格多行注释 */
// C++风格单行注释
# Unix风格单行注释
五、类的注释
package com.cric; import java.util.Date; /* * Dog类 写类的作者和时间 */ public class Dog { private String name;//名字 private int age;//年龄 public String getName() { return name; } public void setName(String name) { this.name = name; } public int getAge() { return age; } public void setAge(int age) { this.age = age; } /** * 吃东西 * @param time */ public void each(Date time){ //吃东西的动作 //DOTO:加入代码 } /** * @param args */ public static void main(String[] args) { // TODO Auto-generated method stub } }
对于每一个类,需要包含一段简明扼要的描述,作者和上一次修改的时间
对于每一个方法,需要包含这个方法的用途,功能,参数以及返回结果
当你在一个团队里面的时候,采用一套注释的标准是非常重要的。当然,使用一种大家都认可的注释约定和工具(例如C#的XML注释和Java的Javadoc)在一定程度上能推动这项任务。
1. 要有礼貌
应当避免没有礼貌的注释,例如“要注意一些愚蠢的用户会输入一个负数”,或者“修正由菜鸟工程师写的愚蠢得可怜的代码而导致的副作用”。这样的注释对于代码的写注释的人来说并没有任何好处,同时你永远都不会知道将来这些注释会被谁来阅读,你的老板,一个客户或者是刚才被你数落的愚蠢得可怜的工程师。
2. 直截了当
不要在注释里面写过多的废话。避免在注释里面卖弄ASCII艺术,写笑话,作诗和过于冗长。简而言之就是保持注释的简单和直接。
3. 使用统一的风格
有些人觉得注释应该让非程序员也能看懂。另外一些人觉得注释需要面对的读者只是程序员。无论如何,正如Successful Strategies for Commenting Code中所说的,最重要的是注释的风格需要统一,并且总是面向相同的读者。就自己而论,我怀疑非程序员是否会去读代码,所以我觉得注释应该面向程序员来写。
4. 把自己想象为注释的读者(事实上就是如此)
当你正在给代码写注释的时候,不仅仅为日后维护你的代码的开发者考虑,同时也设想一下如果自己就是注释的读者
5. 更新代码的时候要更新注释
如果注释没有随着代码的修改而更新,那么这些注释将是毫无意义的。代码和注释需要同步,否则注释只会让维护代码的开发者更加痛苦。需要特别注意的是,一些重构的工具会自动更新代码,但是却没有自动更新注释,那么注释就自然而然地过期作废了。
6. 良好可读性代码是注释的金科玉律
对于很多开发者来说,一个基本的原则就是:让代码自己描述自己。虽然有人怀疑这是由不喜欢写注释的程序员所倡导的一场运动,但是无需解释的代码有很大的好处,这些代码更加容易理解甚至让注释变得没有必要。