snippet-composer:给代码片段加点魔法

2023-10-08 01:10

本文主要是介绍snippet-composer:给代码片段加点魔法,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

导读

snippet 在软件工程领域可译为代码片段,虽然你可能很少有机会编写它,但你一定会在代码编辑器上使用过它。它要么直接集成到编辑器中,要么以插件的形式来进行扩展。就以笔者经常使用的 vscode 为例,在做网页开发时,会安装HTML SnippetsJavascript Snippets等插件,如果使用到框架还会安装框架对应的插件,这些插件内置的代码片段可以极大提高开发效率。

“你可能没有自己编写过代码片段但是你一定享受过代码片段带来的便利性。”

本文以 vscode 为例,指出了代码片段在 vscode 中应用的局限性,即代码片段与代码片段之间没有建立联系,它们是相对孤立的,这导致了当需要编写更复杂更贴近实际业务的代码片段时会遇到困难,而后为了解决这一问题,笔者设计实现了一个用于组合代码片段的工具包:snippet-composer。

vscode 中的 snippet

下面,我们将简要介绍一下 vscode 中代码片段的相关概念和用法,这里只介绍本文提及的部分概念,详细的说明参见官方文档。

  • 基本语法,vscode 中的代码片段语法遵循 TextMate snippet 语法 ,但是不支持执行内置的 shell 代码和\u的用法。 一个代码片段可以使用一个json格式的文件来描述,其键为代码片段的名称,值为描述代码片段的对象。其中必选字段prefix对应了代码片段的触发词;必选字段body是代码片段的主体内容,其值可以为字符串或数组,数组中每个元素对应一行代码;可选字段description用于描述代码片段;可选字段scope为代码片段的作用域。
// in file 'Code/User/snippets/javascript.json'
{"For Loop": {"prefix": ["for", "for-const"],"body": ["for (const ${2:element} of ${1:array}) {", "\t$0", "}"],"description": "A for loop.","scope": "javascript,html"}
} 
  • Tabstops,可译为制表位,决定了在插入代码片段后光标在片段中停留的位置,若有多个制表位可以使用编号排序,通过 Tab 键来切换制表位,在用户输入内容时编号相同的制表位会被同步更新。其语法为$1$2,也可给定默认值和可选值,如${1:another ${2:placeholder}}${1|one,two,three|}$0较为特殊,它决定了最终光标的位置。* 变量,语法为$name${name:default},只能使用 vscode 预定义的变量,如,> * TM_SELECTED_TEXT 当前选中的文本或空字符串
  • TM_CURRENT_LINE 当前行的内容
  • CURRENT_SECONDS_UNIX 自 Unix 纪元以来的秒数
  • RANDOM 6 个随机 Base-10 数字
  • BLOCK_COMMENT_START 示例输出:PHP/*或 HTML<!--

造个轮子给 snippet 加点魔法

业务背景

在介绍轮子之前,我们先讨论一下有没有这样一些场景需要将多个代码片段组合成一个更大的代码片段从而用于描述一个组件或页面模板。

场景一:在开发业务组件开发时,已有一个用于描述通用 react 函数组件的代码片段,一个与业务紧耦合的全局 context 的代码片段,我们需要组合成一个可随主题切换的业务组件代码片段。

/************* React 通用函数组件 snippet *************/
import React from 'react';const $1 = () => {return (<div> $1 </div>)
}
export default $1/************* 全局主题 context snippet *************/import ThemeContext from '@/context';
const theme = useContext(ThemeContext);/************* 组合为一个带全局主题的业务组件 *************/import React from 'react';
import ThemeContext from '@/context';const $1 = () => {const theme = useContext(ThemeContext);return (<div> $1 </div>)
}
export default $1 

场景二:在开发中后台页面时,已有一个代码片段用于描述通用页面布局的 react 函数组件,若干个代码片段分别对应不同业务逻辑的headerfootermenu组件,需要组合成任意数量业务逻辑有差异的中后台页面模板。

/************* 页面布局 React 函数组件代码片段 *************/
import React from 'react';
import Layout from '@/Layout';const $1 = () => {return (<Layout> $0 </Layout>)
}
export default $1
/************* 一些构成页面的组件代码片段 *************/
// 1. header snippet
import React from 'react';
const $1 = () => {return (<header> $0 </header>)
}// 2. footer snippet
import React from 'react';
const $1 = () => {return (<footer> $0 </footer>)
}// 3. menu snippet
import React from 'react';
const $1 = () => {return (<aside> $0 </aside>)
}/************* 组合为一个页面模板 *************/
import React from 'react';
import Layout from '@/Layout';const $1 = () => {return (<Layout><header> $2 </header><footer> $3 </footer><aside> $4 </aside></Layout>)
} 

场景三:在白盒测试时,需要根据文档规定流程进行测试,其中可能包含大量重复的测试逻辑和少量与当前业务相关的逻辑代码,文档中每个测试环节都可以用若干个代码片段描述。(下述示例表示的$Host、$User、$PassWord、$DB为自定义变量,原生代码片段没有提供自定义变量的能力)

/************* 连接数据库代码片段 *************/
import mysql from mysql;
const connection = mysql.createConnection({host : $Host,user : $User,password : $PassWord,database : $DB
});
connection.connect();/************* 断言库与断言代码片段 *************/
import assert from 'node:assert';
connection.query('.....', (err, result) => {assert(result,'it should be true');
});
$0
/************* 组合为完整的测试流程代码片段 *************/
import mysql from mysql;
import assert from 'node:assert';const connection = mysql.createConnection({host : $Host,user : $User,password : $PassWord,database : $DB
});
connection.connect();
connection.query('.....', (err, result) => {assert(result,'it should be true');
});
$0 

以上提到的场景中,vscode 及其插件都没有提供相应的组合能力。

当然,有人会说,那我自己把这些代码片段通过 cv 大法手动组合起来不就完事了,这不需要借助任何工具。其实这纯粹是一个选择问题,如果你使用的代码片段之间不需要建立组合关系,或者代码片段不需要按细粒度划分且几乎不随业务变化,那么完全不需要再额外使用工具包。

那么,在组合代码片段时,我们需要考虑哪几方面的问题呢?

1.对代码片段各个部分重新排序后再组合
2.重组后的代码片段需要对 tabstops 重新编号
3.其他拓展功能

组合多个代码片段

首先,我们回顾一下当代码片段没有提供组合能力时,直接手动拼接多个代码片段得到的结果往往和预期有差异。

当然,除了两两组合外,我们还可以从组合思想出发,更进一步地细化代码片段的粒度,提高复用性。比如,在一个页面模板中,根据业务需要组合不同组件库的组件从而生成不同的页面模板。

对 tabstops 重新编号

在重新组合代码片段后,大多数情况下都要对原有的 tabstops 进行重新编号。比较极端的编号规则有两种,一是所有 tabstops 都不变,二是按出现顺序对序号进行递增。正所谓众口难调,为了减少不必要的误解并简化逻辑。笔者的设计方案是,在组合代码片段后默认 tabstops 的编号不变,但是用户可以通过拓展字段来对组合后的 tabstops 重新编号,具体可参考下面的用法。

自定义变量

虽然 vscode 提供的代码片段能力不像原生的 TextMate 语法 支持 shell 代码内联,但是提供了一些预置的变量,这些变量大多数用来提供一些上下文信息。但是却没有提供用户自定义变量的能力。因此,我们可以在设计代码片段组合能力的时候,可以顺便提供一些简单的用户自定义变量的能力。

当然,自定义变量的能力是受限的,如果要修改变量的值,需要重新生成代码片段,没法在插入代码片段的时候动态计算变量值。因此,它更加适合一定时段内相对不变的常量。不过,它依然能有很多待发掘的潜力,比如用于快速统一或切换代码风格或命名风格,读取 git 配置将作者信息写入到代码注释中。

食用方法

下面,我们将对上面提出的三大功能点:组合编号自定义变量,进行逐一演示。

遵循自上而下设计的原则,我们先对工具包的入口函数展开讨论。

入口函数命名为defineSnippet,需要传入的函数变量有两个,第一个参数传入拓展的代码片段,它在继承了原生代码片段相关字段的基础上拓展了一些字段,第二个变量为一个数组,它存放了需要组合的原生代码片段。最后返回的结果为经组合后新的代码片段。

首先我们放出一个完整的示例程序,然后再逐条介绍示例中涉及到的拓展字段与语法。

/************* snippet1.json *************/
{mysql: {prefix: ['ms'],body: ['import mysql from mysql','mysql.connect($USER_NAME,$USER_PASSWORD,$1);',],},assert: {prefix: ['as'],body: ['import assert from assert','assert(a,1);\rassert(b,$1);\rassert(c,$2);','$0',],},
}
/************* snippet2.json *************/
{utils: {prefix: ['utils'],body: ['function delay() {\r\tsleep($1);\r}','function getPort() {\r\treturn ${2};\r}',],},
}/************* index.js *************/
import snippet1 from "./snippet1.json";
import snippet2 from "./snippet2.json";const newSnippet = defineSnippet(// 参数一为拓展的代码片段,主要负责组合原生代码片段{'Test Case': {prefix: ['tc'],description: 'Test Case',scope: 'javascript',// 重组 snippet1 和 snippet2 的代码片段body: ['${mysql[0]}','${assert[0]}','${mysql[1]}\r${assert[1,3]}','${utils[0,]}',],// 拓展字段extra: {tabstops: {1: ['mysql$1', 'utils$2'],2: ['assert$1'],3: ['assert$2'],4: ['utils$1'],},customVar: {USER_NAME: 'admin',USER_PASSWORD: () => '123',},},},},// 参数二,传入原生代码片段[snippet1, snippet2],
);// 最终组合的结果为原生代码片段
expect(newSnippet).toEqual({'Test Case': {prefix: ['tc'],description: 'Test Case',body: ['import mysql from mysql','import assert from assert','mysql.connect(admin,123,$1);\rassert(a,1);\rassert(b,$2);\rassert(c,$3);\r$0','function delay() {\r\tsleep($4);\r}\rfunction getPort() {\r\treturn ${1};\r}',],},
}); 

1.为了将不同代码片段的body部分进行重组,我们定义了表示body元素的语法为${代码片段名[body索引值]},同时还支持部分切片语法。

// snippet.json
{foo: {prefix: ['foo'],body: ['line0','line1','line2',],},
}// body replace result'${foo[0]}' -> 'line0'
'${foo[0,1]}' -> 'line0\tline1'
'${foo[1,]}' -> 'line1\tline2' 

2.为了对代码片段的 tabstops 编号,我们拓展了字段extra.tabstops,其语法为{新编号:[代码片段名称$body索引值]}

// snippet.json
{foo: {prefix: ['foo'],body: ['foo code $1','foo code $2',],},bar: {prefix: ['bar'],body: ['bar code $1','bar code $2',],}
}
// tabstops demo
{....body:['${foo[0]}','${foo[1]}','${bar[0]}','${bar[1]}'],extra: {tabstops:{2:['foo$2','bar$1'],3:['bar$2'],}}
} 
// Compose bodies, and then the new bodies are as follows after replacing tabstops.
body: ['foo code $1','foo code $2',
- 'bar code $1',
+ 'bar code $2',
- 'bar code $2',
+ 'bar code $3'
] 

3.最后,拓展字段extra.customVar负责管理自定义变量的计算逻辑,其语法为$自定义变量名

/************* snippet.json *************/
{mysql: {prefix: ['ms'],body: ['import mysql from mysql','mysql.connect($USER_NAME,$USER_PASSWORD,$1);',],},
}
// customVar demo
{.....extra: {customVar: {USER_NAME: 'admin',USER_PASSWORD: () => '123',},}
}'mysql.connect($USER_NAME,$USER_PASSWORD,$1);' -> 'mysql.connect(admin,123,$1);' 

补充说明:由于 snippet-composer 的入口函数defineSnippet是一个纯函数,因此在实际使用中还需要根据宿主环境提供的文件接口将生成的代码片段写到文件中。CodeSanbox上给出了在不依赖文件系统时的演示样例,而github上的样例给出了当宿主环境为 nodejs,编辑器为 vsocde 时,将生成的代码片段写入到项目根目录的示例代码。

改进方向

  • 易用性:在产品投入市场前,任何产品形态都只是开发者的一厢情愿,前期开发精力最应投入到其易用性的改造上。当然,围绕工具包的生态环境构建也是保证易用性非常重要的一环,比如提供Code2Snippet、Snippet2Doc、Doc2Snippet、ExtractSnippet 等能力。* 可视化:笔者比较推崇的一种思想是,将一切效能工具可视化,这也是规范流程的一种方式。只是,提供可视化能力往往需要付出比其自身更高的开发和维护成本,并且优秀的可视化方案本身就是凤毛麟角。* 性能方向:作为一个对环境零依赖的工具包,可以选择使用更高效的编程语言来重写它,如 c++、rust。但前提是这个工具包确实在大规模场景下遇到了性能瓶颈,否则大概率会浪费人力与提高社区维护成本(从编程语言学习曲线和人数上看)。从具体代码实现的维度浅谈团队规范

在前端开发领域,现在各个大厂都在面向开发者火拼组件库和脚手架。其中,一些组件库还开放了物料市场以及定制化的组件包发布能力。

在笔者看来,组件库规范了交互逻辑和设计风格,脚手架规范了开发环境、编码风格和研发链路。而本文想做的事情,其实是做好具体业务代码实现上的规范,而 snippet-composer 只是这个想法的一个最低成本的载体。

对具体实现代码的规范极有可能是一个伪需求,这是因为一是业务代码极其灵活多变,二是规范本身伴随着成本,规范越细化执行和维护成本越高。在大厂里,由于每个人的编程能力都较高且都具备独立思考能力,再加上有完整的基建支持,所以过度规范反而约束了创造力。

那么笔者为什么还要做这件事?

有两个出发点,第一个源于自身经历,在笔者实习时,接触到的项目是一个已经迭代为巨无霸的中台项目。该项目的主要特点为, 业务组件多且同类型的组件经常重名;当使用 context 来管理 react 组件的数据流时,context 也经常重名,需要不停回溯到父组件才能知道具体引用了哪个 context;引入同类型的工具库增大产物体积,提高了项目维护的潜在风险,如 A 页面使用 moment.js 而 B 页面使用 dayjs 来解决国际化问题。上述问题无形之中提高了新人上手的学习成本以及团队协作的成本。一个维护良好的文档或许可以缓解这些问题。当使用文档来约束具体编程细节时,一般强调简明扼要,不可能事无巨细的把代码一一贴上,而且程序员的思考逻辑往往是 Talk is cheap, show me the code.因此,代码片段加上良好的注释能够更加直白地表述这些具体代码实现细节,在已有代码片段的基础上,文档只需要生成代码片段的大纲即可(甚至生成大纲的步骤可以从代码片段的注释中提出出来)。

第二个源于笔者对一些小型开发团队的观察。为了避免不必要的讨论,我们对团队的特征再进行更详细的描述:一是团队项目需要长期开发和维护,二是团队成员的流动性高且成员的水平参差不齐,三是团队没有任何基建的支持。这样一个看似 DEBUFF 叠满的开发团队恰恰是大多数团队的现状。此时,由团队中坚力量创建和维护的代码片段除了可以直观地低成本地分担部分代码规范的压力,还能帮助新人从代码片段入手快速熟悉项目,一定程度上减少"抄都抄歪来,抄都不会抄"的尴尬场面。

再回到本文,代码片段的创建和维护应该由谁来负责。以笔者的拙见,如果团队经常是一神带四坑的状态,那么则由能力最强的人来负责;如果团队整体对业务都较为熟悉,那么当需求倒逼代码片段更新时,由负责该需求的成员来负责本次更新。当然,无论是什么团队,代码片段的更新都要及时同步到团队的所有成员。

总结

本文针对代码片段的组合问题展开了深入讨论,并设计实现了工具包 snippet-composer 来分别从以下三方面来增强代码片段的组合能力。

1.代码片段重新组合
2.制表符 tabstops 重新编号。
3.自定义变量。

当然,snippet-composer 只是一个在具体代码实现层面做团队规范的切入点,与之配套的生态环境构建才是做成这件事的关键。

这篇关于snippet-composer:给代码片段加点魔法的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/161683

相关文章

Java中有什么工具可以进行代码反编译详解

《Java中有什么工具可以进行代码反编译详解》:本文主要介绍Java中有什么工具可以进行代码反编译的相关资,料,包括JD-GUI、CFR、Procyon、Fernflower、Javap、Byte... 目录1.JD-GUI2.CFR3.Procyon Decompiler4.Fernflower5.Jav

javaScript在表单提交时获取表单数据的示例代码

《javaScript在表单提交时获取表单数据的示例代码》本文介绍了五种在JavaScript中获取表单数据的方法:使用FormData对象、手动提取表单数据、使用querySelector获取单个字... 方法 1:使用 FormData 对象FormData 是一个方便的内置对象,用于获取表单中的键值

Vue ElementUI中Upload组件批量上传的实现代码

《VueElementUI中Upload组件批量上传的实现代码》ElementUI中Upload组件批量上传通过获取upload组件的DOM、文件、上传地址和数据,封装uploadFiles方法,使... ElementUI中Upload组件如何批量上传首先就是upload组件 <el-upl

Rust中的Drop特性之解读自动化资源清理的魔法

《Rust中的Drop特性之解读自动化资源清理的魔法》Rust通过Drop特性实现了自动清理机制,确保资源在对象超出作用域时自动释放,避免了手动管理资源时可能出现的内存泄漏或双重释放问题,智能指针如B... 目录自动清理机制:Rust 的析构函数提前释放资源:std::mem::drop android的妙

C++使用栈实现括号匹配的代码详解

《C++使用栈实现括号匹配的代码详解》在编程中,括号匹配是一个常见问题,尤其是在处理数学表达式、编译器解析等任务时,栈是一种非常适合处理此类问题的数据结构,能够精确地管理括号的匹配问题,本文将通过C+... 目录引言问题描述代码讲解代码解析栈的状态表示测试总结引言在编程中,括号匹配是一个常见问题,尤其是在

Java调用DeepSeek API的最佳实践及详细代码示例

《Java调用DeepSeekAPI的最佳实践及详细代码示例》:本文主要介绍如何使用Java调用DeepSeekAPI,包括获取API密钥、添加HTTP客户端依赖、创建HTTP请求、处理响应、... 目录1. 获取API密钥2. 添加HTTP客户端依赖3. 创建HTTP请求4. 处理响应5. 错误处理6.

使用 sql-research-assistant进行 SQL 数据库研究的实战指南(代码实现演示)

《使用sql-research-assistant进行SQL数据库研究的实战指南(代码实现演示)》本文介绍了sql-research-assistant工具,该工具基于LangChain框架,集... 目录技术背景介绍核心原理解析代码实现演示安装和配置项目集成LangSmith 配置(可选)启动服务应用场景

Python中顺序结构和循环结构示例代码

《Python中顺序结构和循环结构示例代码》:本文主要介绍Python中的条件语句和循环语句,条件语句用于根据条件执行不同的代码块,循环语句用于重复执行一段代码,文章还详细说明了range函数的使... 目录一、条件语句(1)条件语句的定义(2)条件语句的语法(a)单分支 if(b)双分支 if-else(

MySQL数据库函数之JSON_EXTRACT示例代码

《MySQL数据库函数之JSON_EXTRACT示例代码》:本文主要介绍MySQL数据库函数之JSON_EXTRACT的相关资料,JSON_EXTRACT()函数用于从JSON文档中提取值,支持对... 目录前言基本语法路径表达式示例示例 1: 提取简单值示例 2: 提取嵌套值示例 3: 提取数组中的值注意

CSS3中使用flex和grid实现等高元素布局的示例代码

《CSS3中使用flex和grid实现等高元素布局的示例代码》:本文主要介绍了使用CSS3中的Flexbox和Grid布局实现等高元素布局的方法,通过简单的两列实现、每行放置3列以及全部代码的展示,展示了这两种布局方式的实现细节和效果,详细内容请阅读本文,希望能对你有所帮助... 过往的实现方法是使用浮动加