代码注释语法及规范参考

在实际开发中，我们在定义一些类或组件时，经常要写一些注释。前端注释如下：

/**
* @property {String} 日程拥有者的ID
* @desc 用于加载日程信息时指定 拥有者
* ### 示例:'T001'
*/
ownerID: null,
/**
* @property {Array}  日程拥有者的ID 数组
* @desc 用于加载日程信息时指定 拥有者
* # 示例:['T001']
*/
ownerArr: [],
/**
* @property {String}  日程显示及添加类型
* @desc 用于加载日程信息时指定类型 以及 新建时固定类型
* @value `plan` 计划 `act` 活动 
* ### 示例:'plan'
*/
type: null,

 

当鼠标悬浮在其上时，可以看到这些注释信息

可以看到有 @property @desc 等等标签 还有些是 ### 

为什么会有这些？主要由于有一种参考规范

注释语法规范

1.jsDoc

整体js注释规范参照的是 jsDoc 

像是参数注释说明可以用 @param

/**
 * @func
 * @desc 一个需要string类型参数的函数
 * @param {string} a - 参数a
 */
function bar(a) {}

其他的具体规范可以参考 jsDoc 规范导航

2.markDown

在实际写一些描述时，用到的是markDown语法来标记

例如，想声明 示例时 可以用 ### 

/**
        * @property {String} 日程拥有者的ID
        * @desc 用于加载日程信息时指定 拥有者
        * ### 示例:'T001'
        */

 ### 就是markDown 里 用于声明标题信息的

具体MarkDown语法 可以参考 markDown语法大全简版
 

---

 

js注释

1.前端在VS Code开发的话，可以使用Document This 插件

 

2.在扩展里搜“Document”,然后安装，安装好后，重启VS Code,

3.然后将鼠标光标放置在需要添加注释说明的方法前（或上部）,使用 Ctrl + Alt + D ，生成模板后填写必要信息

ps:快捷键 也可以自己去 Vs Code【快捷键】设置调整

 

服务端方法添加说明注释

有时我们经常会在一些服务端的方法里看到一些注释，像如下c#例子：

#region 重载公告的缓存
/// <summary>
/// 重载公告的缓存
/// </summary>
/// <param name="reload"></param>
public static void WriteNoticeMemory(bool reload)
{ 
        
}
#endregion

这些注释的作用啥？

#region  + #endregion 

仅是用来包裹方法体的，可以将一段很长的包裹起来，方便整体阅读

summary 

用于外部调用方法时，显示提示，

当鼠标悬浮在方法名上 就会显示的提示

summary的添加方式：

在方法名前输入 ///  后点回车即可