CBML
代码块标记语言(英文:Code Block Markup Language,CBML)是为标记代码区域设计的一种标记语言。
背景
为什么要标记代码区域?
目前标记代码主要功能
- 表示一段代码约定的含义
如 新浪首页 源代码,广告部分
<!-- 乐居广告脚本 begin-->
<script src="http://d5.sina.com.cn/litong/zhitou/leju/leju.js"></script>
<!-- 乐居广告脚本 end-->
- 指定一段代码编译器处理的方式
如 C 语言中的宏定义
#include "headfile"
#ifdef DEBUG
fprintf("variant=%d", variant);
#endif
- 告诉编辑器这段代码可以折叠
如 C# 中
#region
#region safe
if (arr.length < 2) {
return;
}
#endregion
- 告诉代码质检工具相应规则
如 jslint
console.log('hello'); // jshint ignore:line
/*jshint unused:true, eqnull:true */
/* jshint ignore:start */
var define;
var require;
var esl;
/* jshint ignore:end */
- 表示这段代码的映射表
如脚本编译后的 sourceMappingURL
/*# sourceMappingURL=page.css.map */
总之就是为了给一段代码添加额外的信息
相信未来还有抱着各种各样代码块标记需求产生,面对这些复杂并未知的变化我们能不能把这件事做得优雅,所以我想到了 CBML
。
现有定义代码块的问题
- 不容易学习和记忆;
是前缀还是后缀?是
begin
还是start
<!-- 乐居广告脚本 begin-->
/* jshint ignore:start */
- 是否存在闭合不明显;
/*jshint unused:true, eqnull:true */
要不要闭合?
- 各语言间没有统一的解决方案。
C# 里用
#region
,sourceMappingURL 用/*# sourceMappingURL=...*/
代码块标记基本需求
-
不影响开发期代码调试
-
学习成本低
-
支持各种主流代码文件
-
扩展性高
-
歧义小
思路
XML 就已经是很好的标记语言了,基于 XML 扩展,就能满足如上各种基本需求。
所以思路很简单:将 XML 标记放到各种语言的多行注释里!(机智)
代码块定义
类 C 语言
/*<tag attrs />*/
/*<tag attrs>*/
int i = 1024;
/*</tag>*/
/*<tag attrs>
int i = 4096;
</tag>*/
Python
'''<tag attrs />'''
'''<tag attrs>'''
i = 1024
'''</tag>'''
'''<tag attrs>
i = 4096
</tag>'''
类 Pascal 语言
(*<tag attrs />*)
(*<tag attrs>*)
const
I: Integer = 1024;
(*</tag>*)
(*<tag attrs>
const
I: Integer = 4096;
</tag>*)
类 XML 语言
这样看上去有点累赘
<!--<tag attrs />-->
<!--<tag attrs>-->
<h1>1024</h1>
<!--</tag>-->
<!--<tag attrs>
<h1>4096</h1>
</tag>-->
所以选择了这样:
<!--tag attrs /-->
<!--tag attrs-->
<h1>1024</h1>
<!--/tag-->
<!--tag attrs>
<h1>4096</h1>
</tag-->
使用
只要 tag 不要冲突,代码块之间就能和平相处了
示例
/*<jshint ignore>*/
var define;
var require;
/*</jshint>*/
/*<editor region="safe">*/
if (arr.length < 2) {
return;
}
/*</editor>*/
/*<jdists encoding="aaencode">
/*</jdists>*/
后续
- CBML 全局 tag 注册
- CBML 相关工具
- 社区建设
- 运营推广
- 文档全球化