关于推进可追溯代码来历的方案
缘由
在互联网上,许多技能博客和文章引进代码段来协助读者了解技能思路或记载对某个大型模块的原理剖析和了解。然而,由于版别管理和技能变化,许多前史文章在读者读到精华时,发现引进的代码块没有来历信息,导致不能对这个思路进行完好的了解,影响了读者的学习作用。
和ChatGpt 在关于这个问题上,做了一番具体的评论,由此萌发了让我推进代码可溯源的动力。
在博客或文章中引进代码块但没有引进代码的来历或许导致以下问题:
- 缺乏参阅和引证:不供给代码的来历将使读者难以查找和验证代码的准确性和牢靠性。读者或许无法判别代码的作者、代码的版别或其他相关信息。
- 侵权问题:假如你从其他来历仿制了代码但没有引证或提及原始作者或代码来历,这或许构成侵权行为,违反了常识产权法律和道德规范。
- 可信度和可复现性问题:供给代码的来历能够增强博客或文章的可信度。读者能够参阅原始来历来验证代码,并取得更多的上下文信息。此外,假如读者想要在自己的环境中复现代码,代码的来历能够供给必要的辅导和依赖信息。
为了处理这些问题,主张在博客或文章中引进代码块时,尽量供给代码的来历信息。这能够经过增加注释、链接到代码库房或引证出处等方法来完成。这样能够供给更完好的信息,增加文章的可信度,一起尊重代码作者的权益。
差异
传统的Markdown语法
传统的Markdown语法中,并没有内置的方法来指定代码块的高亮行数。通常,Markdown的代码块仅仅用于展现代码,而不支撑精确指定高亮行数的功用。
然而,一些扩展的Markdown解析器或编辑器或许供给了自界说的语法或插件,以支撑在代码块中指定高亮行数。这些扩展能够依据不同的东西和插件而有所不同。
以下是一些常见的Markdown扩展和东西,它们或许供给了在代码块中指定高亮行数的功用:
- GitHub Flavored Markdown (GFM)
GFM支撑在代码块中运用类似{highlight}的语法来指定高亮行。例如:
```java {highlight=[1,3-5,7]}
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, world!"); // 第1行、第3到第5行、第7行高亮
}
}
- Markdown Extra
Markdown Extra是一种扩展的Markdown语法,支撑类似GFM的高亮行语法。具体语法或许因东西而异,请查阅Markdown Extra的文档以了解具体信息。 - VS Code和其他编辑器插件
某些编辑器(如VS Code)供给了Markdown插件,能够运用特定的语法来指定高亮行。这些插件通常运用自界说的语法或标记来完成,具体的语法和用法能够查阅插件的文档。 请注意,这些功用的可用性和具体的语法取决于你所运用的Markdown解析器、编辑器或扩展。主张查阅相关东西的文档以了解是否支撑在代码块中指定高亮行数,并找到相应的语法或插件来满足你的需求。 - Github
-
Github Markdown 有人对此有一些主张 Allow to highlight lines in a code block (github flavored markdown) #42489
-
Github permalink github供给一种能够支撑高亮以及版别信息的永久链接,给这个项目供给了思路,经过 Shift 能够多选行数,然后右击挑选 permalink(永久链接).
OomAdjuster.java#L3127-L3129
-
新的规范界说
和 ChatGpt 评论怎么规划新的规范过程中,关于新的规范界说,它也持续为了输出了主意:
- 规划一个引进链接的代码块 能够考虑以下格局:
```java [链接名](链接地址)
// 代码内容
```
这样就能够在代码块中增加一个链接,链接名将显示为可点击的文本,点击后会跳转到指定的链接地址。
- 代码块中一起指定起始行和高亮行数 你能够考虑以下格局:
```java {起始行号}-{完毕行号} {高亮行号1} {高亮行号2} ...
代码内容
例如,假如你想指定起始行为第3行,高亮第4行和第5行的Java代码块,能够运用以下格局:
```java {3-} {4 5}
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, world!"); // 第4行高亮
System.out.println("Welcome!"); // 第5行高亮
}
}
在上述示例中,起始行号为3,完毕行号为空,表明从第3行到代码块完毕的一切行。高亮行号1和高亮行号2别离表明第4行和第5行。
请注意,这仅仅一种示例规划,具体的完成方法或许因你运用的Markdown解析器或编辑器而有所不同。主张查阅你所运用的东西的文档,以了解是否支撑在代码块中一起指定起始行和高亮行,并查找相应的语法或插件来完成你的需求。
完成
完好界说
```语言 {起始行-完毕行} {高亮起始行-高亮完毕行} (LINK)
// 代码内容
- 例子
- 完好写法
```java {3125-3131} {3126-3130} (https://github.com/10cl/fwkdev/blob/android-13.0.0_r52/dev/src/frameworks/base/services/core/java/com/android/server/am/OomAdjuster.java#L3125-L3131) // Use current adjustment when freezing, set adjustment when unfreezing. if (state.getCurAdj() >= ProcessList.CACHED_APP_MIN_ADJ && !opt.isFrozen() && !opt.shouldNotFreeze()) { mCachedAppOptimizer.freezeAppAsyncLSP(app); } else if (state.getSetAdj() < ProcessList.CACHED_APP_MIN_ADJ) { mCachedAppOptimizer.unfreezeAppLSP(app, oomAdjReason); } } ```
- 作用
经过点击 view raw 即可直达代码来历以及关于的版别信息。
页面作用见: source.toscl.com
兼容的挑选
考虑到许多 markdown 解析东西,对新的规范支撑有必定的工作量以及兼容性问题,经过原有的 markdown 格局,也能完成代码块的可追溯, 这儿也鼓励这种新的方法来写代码块。
- 写法
```java // Use current adjustment when freezing, set adjustment when unfreezing. if (state.getCurAdj() >= ProcessList.CACHED_APP_MIN_ADJ && !opt.isFrozen() && !opt.shouldNotFreeze()) { mCachedAppOptimizer.freezeAppAsyncLSP(app); } else if (state.getSetAdj() < ProcessList.CACHED_APP_MIN_ADJ) { mCachedAppOptimizer.unfreezeAppLSP(app, oomAdjReason); } } ``` [OomAdjuster.java#L3125-L3131](https://github.com/10cl/fwkdev/blob/android-13.0.0_r52/dev/src/frameworks/base/services/core/java/com/android/server/am/OomAdjuster.java#L3125-L3131)
- 作用
OomAdjuster.java#L3125-L3131// Use current adjustment when freezing, set adjustment when unfreezing. if (state.getCurAdj() >= ProcessList.CACHED_APP_MIN_ADJ && !opt.isFrozen() && !opt.shouldNotFreeze()) { mCachedAppOptimizer.freezeAppAsyncLSP(app); } else if (state.getSetAdj() < ProcessList.CACHED_APP_MIN_ADJ) { mCachedAppOptimizer.unfreezeAppLSP(app, oomAdjReason); } }
一键引证
由于我个人长时刻在和 AOSP 这套大型源码打交道,用这个方法假如手动来写,难免有点困难,所以专门开发了一款插件用来一键仿制指定代码块的 Markdown 款式:
MarkdownQuote是JetBrains插件,能够协助你在IDE中高效地仿制代码围栏,更多细节请参阅SourceCodeTrace项目。
现在这个插件已经上架到 Jetbrains IDE 商场,能够直接在 IDE中: File -> Settings -> Plugins -> 搜索 “MarkdownQuote” 装置体会。
解析的支撑
由于是新的款式,还需求有解析的支撑,我差不多运用了10年的 Sublime,比较热衷于运用这款轻量级的编辑器,管理了许多文字上的工作,所以预备在 Sublime 上测验。
Sublime 上依据 pymdownx 有一款 MarkdownPreview 插件,我在这个上面改了一版解析的流程,可是作为网站的显示,中心还需求一些工作要做,暂时没法上线。
vuepress 是比较快捷的在线网站生成结构,依据 markdown-it 生成 markdown款式,因而,依据这个结构上,写了一款插件,并上架到了 NPM: markdown-it-quote是一个用于markdown-it的插件,支撑多种代码围栏功用。
现在一切开发的功用均是开源的方式,旨在推行代码的可溯源。
SourceCodeTrace 的意义
SourceCodeTrace(源代码追溯)这个安排称号能够传达以下意义:
- 源代码的追溯性:强调追寻代码的来历、前史和演化过程,以保证代码的可信度和可追溯性。这能够包含引进代码的来历、版别控制、修正前史等方面。
- 代码来历的追寻:重视追寻代码的来历,保证代码的原始作者得到恰当的认可和归属。这能够涉及到代码的引证、引进作者信息、恪守开源许可证等方面。
- 代码溯源:强调代码的起源,能够追溯到特定的项目、库、团队或个人。这有助于了解代码的布景、用途和背面的规划思维。 经过挑选 “SourceCodeTrace” 作为安排称号,你传达了一个关于追溯源代码的重要性的信息。这个安排能够致力于推进代码块来历的规划和实践,提倡代码的可信度、来历可追溯性以及对原始作者的尊重和认可。这有助于树立一个注重代码牢靠性和常识产权的开发和协作环境。
Logo的规划
描绘SourceCodeTrace安排的或许的logo规划方案: Logo规划:
- 标志:运用一个简练而有力的标志来代表SourceCodeTrace。能够测验结合代码和追寻的元素,如拼图、箭头或放大镜等,以展现源代码的追溯和追寻的概念。
- 字体:挑选现代、明晰的字体,使安排称号”SourceCodeTrace”易于辨识。
- 颜色:挑选与代码相关的色彩,如深蓝、绿色或灰色,以传达专业性、牢靠性和技能性。能够运用渐变色或不同色调来增加视觉吸引力。 示例规划描绘: SourceCodeTrace的logo规划是一个简练而现代的标志。标志的核心元素是一个由拼图和箭头组成的图形,形象地代表了对源代码的追溯和追寻。箭头的指向表明SourceCodeTrace安排致力于引导和推进代码块来历的规划。字体运用了明晰而简略的无衬线字体,以突出安排称号”SourceCodeTrace”。颜色方面,我们挑选了深蓝色作为首要色调,结合浅蓝色渐变作用,以传达专业性和牢靠性。
请注意,这仅仅一个示例规划描绘,你能够依据自己的喜好和需求进行调整和修正。当规划Logo时,保证它与你的安排价值观和宣传方针相一致,并尽量坚持简练、易识别和具有独特性。最重要的是,保证Logo能够在不同尺寸和布景下坚持明晰可见。假如需求进一步的规划或修正,能够咨询专业的图形规划师或运用在线Logo规划东西来完成你的主意。
怎么推行这样的安排
要推行你的安排和传播安排的思维,你能够采取以下战略:
- 树立一个网站或在线渠道:创立一个专门的网站或在线渠道,介绍你的安排、主旨和使命。在网站上供给关于代码块来历规划的信息、最佳实践、指南和资源,以便开发者和社区成员参阅和学习。
- SourceCodeTrace
- 交际媒体宣传:使用交际媒体渠道,如Twitter、LinkedIn、Facebook等,树立安排的交际媒体账号。定时发布有关代码块来历的相关内容,包含观念共享、实用技巧、职业新闻、事件和活动等,吸引重视者并扩展影响力。
- (微博、Twitter)
- 写博客或技能文章:编撰关于代码块来历规划的博客文章或技能文章,并在个人博客、技能渠道或开发者社区上发布。经过共享见解、经历和最佳实践,吸引读者的重视并传播安排的思维。 -(经过该新的规范写源码剖析相关的博文,比方先以AOSP这套大的源码做剖析)
- 参加技能社区和活动:活跃参加技能社区、开发者论坛和相关职业活动。参加评论、回答问题、共享经历,并提到你的安排和推进代码块来历的思维。树立个人和安排的声誉和影响力。
- (在渠道共享观念,答疑解惑)
- 协作和协作伙伴联系:与其他安排、社区或个人树立协作伙伴联系,一起推行代码块来历的规划和实践。协作能够包含一起举办活动、协作编撰文章或开发东西,一起传播安排的思维。
- 教育和训练:供给关于代码块来历规划和最佳实践的教育和训练。能够安排在线研讨会、工作坊、训练课程等,向开发者和技能社区传授相关常识和技能。
- (做一些视频介绍一些源码的解析)
- 开源项目和东西:开发开源项目或东西,以促进代码块来历的规划和实践。经过开源项目的运用和奉献,推进安排的思维并取得更多的曝光和支撑。
- (JetBrains IDE 插件、sublime 插件、 vuepress 插件) 以上战略能够彼此结合,依据你的资源和方针受众来制定推行方案。持续不断地供给有价值的内容、活跃参加社区和树立杰出的协作联系,将有助于扩展你的安排的影响力和传播你的思维。
推进的意义
推进代码块来历的规划和传播相关的思维是有意义的。以下是一些原因:
- 进步代码可信度:指定代码块的来历能够增加代码的可信度。当读者知道代码的来历并能追溯其前史和演化过程时,他们更有信心运用和参阅这些代码。
- 保护常识产权:经过推行代码块来历的规划,强调了对代码作者和原始来历的尊重和认可。这有助于保护常识产权,鼓励开发者恪守开源许可证和版权规定。
- 促进协作和共享:清晰代码块的来历能够促进开发者之间的协作和共享。开发者能够更容易地找到和引证他人的代码,然后推进常识沟通和协作。
- 进步代码可维护性:了解代码块的来历有助于进步代码的可维护性。当需求对代码进行修正、修正漏洞或增加新功用时,了解代码的来历能够更好地了解其规划意图和依赖联系。
- 社区建造和奉献:推进代码块来历的规划能够为技能社区的建造和奉献做出奉献。经过共享最佳实践、供给东西和资源,促进开发者之间的沟通和一起成长。 尽管推行代码块来历的规划或许需求必定的努力和时刻,但它关于进步代码质量、常识保护和社区建造都具有重要意义。经过传播这个思维,你能够为开发者和技能社区带来活跃的影响,并促进更加牢靠和可持续的软件开发实践。
相信技能,传递价值
假如你有更好的主张,请在 Github ISSUE 给我供给更具体的主张, 谢谢。