文章贴代码指南

在写技术相关的文章,难免会需要贴一些代码,但贴代码也有讲究,并非随便就可以贴一贴,因此,这篇文章我给你分享一下,我们应该如何贴代码。

贴代码的场景

贴代码一般来说,主要有以下几个场景:

  1. 函数分析:有些时候,我们需要对函数进行分析, 以告诉读者,为什么是这样的作用。
  2. 修改前后对比:对于一些需要读者对文件进行修改的场景,我们需要告诉读者,应该如何修改才是正确的。
  3. 代码逻辑分析:对于一些特别大的项目,我们可能会出现对整个项目进行分析,这时,我们需要告诉读者,具体的处理逻辑是什么。

那么,具体我们应该如何贴代码呢?我们可以按照场景,来一一说明。

场景分析

1. 函数分析

在我看来,能够在一屏内看完的代码,我们都可以将其归类为函数分析类型的代码,他们的普遍特点是代码比较短,但每段代码都有其价值,基本没有删除代码的空间。

对于函数分析的场景,因为单个函数的长度并不是很长,我们可以考虑直接贴代码。这种场景下,代码不应当仅仅是贴图就可以了,你需要在代码中加入一些注释,来说明具体的每一部分都是什么。

对于有行号支持的平台, 你在写文章时,还需要说明是第几行的代码,方便读者找到对应的代码。这样可以让读者以更简单的方式来完成代码的学习。

对于一些支持语言设定的平台,你可以利用 Markdown 的语法(相关语法可以在 markdown.tips 中找到),来完成代码高亮的设置。对于一些富文本编辑器,则可以直接使用编辑器自带的工具来完成。

此外,markdown 支持在代码高亮语法后加上语言,来指定特定的高亮方案,具体用法如下:

```javascript
here is javascript code
```

2. 修改前后对比

修改前后对比的特点是代码在前后发生了改变,因此需要同时提供两份代码,或者是在某一部分代码中标记要如何修改。

有些时候,我们会遇到一些场景,比如要修改一些方法和函数,此时,大部分人的操作是选择贴两份代码,或者是在修改后的代码中加入注释,来说明代码的修改的点。

这里,我为你推荐一个工具,来帮助你把这件事做的更好。

你可以使用 DiffChecker 提供的工具,来完成这一工作。

DiffChecker 提供了 Web 端的 Diff 工具,你可以将原代码和修改后的代码都加入进去,并在下方的时限中选择 Store forever,这样就可以生成一个永久可用的 DIFF 链接,你只需要将修改后的代码贴出来,并附上这样的一个 DIff 链接,就可以实现非常好的效果了。

https://www.diffchecker.com/wmbjedq7

3. 代码逻辑分析

代码逻辑分析类型的特点是所需要看的代码、方法遍布于不同的文件,所需要看的代码也分布在不同的代码中,因此,如果直接贴代码的话,可能你需要贴非常多的代码。

对于一些需要进行大的代码逻辑的分析的时候,我们贴代码是一个不经济的行为,因为会导致我们的文章中出现大量的代码,但是产生的效果不好。在处理这种类型的贴代码时,我们需要考虑的是,用图的形式,来替代代码。

因为这种类型的文章重要的是讲究设计的思路,而不是去探究具体的细节某一个方法内用了哪个函数,你需要讲明白整体方案的架构,而不是某一个具体的函数。

总结

这次课程,我们分享了贴代码的场景以及对应的方法,如果你有其他的场景,不妨。

results matching ""

    No results matching ""