代码注释规范

代码注释规范

一、后端代码注释

1.类（接口）注释

(1)使用swagger的项目

@Controller
@RequestMapping("/testController")
@Api(value="Controller的描述")
public class TestController {
	...
	...
}

/**
 * 
* @TODO: （对service类进行功能描述） 
* @author: Administrator 
* @date: date{time} （日期）
 */
public interface TestService {
	...
	...
}

(2)不使用swagger的项目

/**
 * 
* @TODO: （对Controller类进行功能描述） 
* @author: Administrator 
* @date: date{time} （日期）
 */
@Controller
@RequestMapping("/testController")
public class TestController {
	...
	...
}
/**
 * 
* @TODO: （对Service类进行功能描述） 
* @author: Administrator 
* @date: date{time} （日期）
 */
public interface TestService {
	...
	...
}

2.方法注释

(1)使用swagger

1)1个参数

	@ResponseBody
   	@ApiOperation(value="获取信息", notes="根据输入信息获取信息")
   	@ApiImplicitParam(name = "param1", value = "参数1", required = false, dataType = "String")
   	@RequestMapping(value = "/testFunction", method = RequestMethod.POST)
   	public Result testFunction(String param1) {
		...
		...
	}

2)多个参数

	@ResponseBody
   	@ApiOperation(value="获取信息", notes="根据输入信息获取信息")
   	@ApiImplicitParams({
    	@ApiImplicitParam(name = "param1", value = "参数1", required = false, dataType = "String")
	    @ApiImplicitParam(name = "param2", value = "参数2", required = false, dataType = "String")
    	@ApiImplicitParam(name = "param3", value = "参数3", required = false, dataType = "String")
		@ApiImplicitParam(name = "param4", value = "参数4", required = false, dataType = "String") })
   	@RequestMapping(value = "/testFunction", method = RequestMethod.POST)
   	public Result testFunction(String param1, String param2，String param3，String param4) {
		...
		...    
}

(2)不使用swagger

/**
	 * 
	* @TODO:（方法功能描述） 
	* @param param1
	* @param param2
	* @return（展示方法参数和返回值）
	 */
@ResponseBody
@RequestMapping("/testFunction")
	public String testfunction(String param1,String param2) {
			....
}

3.全局变量注释

	/** 输入全局变量的注释. */
	private final static Logger log = LoggerFactory.getLogger(WechatDownload.class);

4.字段/属性注释

(1)使用swagger

@ApiModel(value = "测试信息")
public class Test {

	@ApiModelProperty(value = "id")
	private String id ;

	@ApiModelProperty(value = "名称")
	private String name;

	@ApiModelProperty(value = "类型")
	private Integer type;
   	……
}

(2)不使用swagger

/**
 * 
* @TODO: Test实体类 
* @author: Administrator 
* @date: 2018-11-7 15:53:37 
 */
public class Test {

	private String id ; 			//id

	private String name;			//名称

	private Integer type;			// 类型

	……
}

Swagger注释API详细说明：

https://blog.csdn.net/xupeng874395012/article/details/68946676/

二、前端代码注释

1.HTML注释

这是一段普通的段落。

2.JavaScript、CSS注释

(1)单行注释

/* 黑色16象素文字 */ 
.dreamdublack16px 
{ 
	color:black; 
	font-size:16px; 
} 
// 输出标题： 
document.getElementById("myH1").innerHTML="欢迎来到我的主页"; 

(2)多行注释

/* 
下面的这些代码会输出 
一个标题和一个段落 
并将代表主页的开始 
*/ 
document.getElementById("myH1").innerHTML="欢迎来到我的主页";
document.getElementById("myP").innerHTML="这是我的第一个段落。";

(3)行末注释

var x=5; // 声明 x 并把 5 赋值给它 
var y=x+2; // 声明 y 并把 x+2 赋值给它