从实际代码开始编写好的示例
创始人
2024-03-02 07:55:39
0

当编写程序时,我花费了大量时间在编写好的示例上。我从未见过有人写过关于如何写出好的示例,所以我就写了一下如何写出一份好的示例。

基础思路就是从你写的真实代码开始,然后删除不相关的细节,使其成为一个独立的例子,而不是无中生有地想出一些例子。

我将会谈论两种示例:基于真实案例的示例和奇怪的示例

好的示例是真实的

为了说明为什么好的案例应该是真实的,我们就先讨论一个不真实的案例。假设我们在试图解释 Python 的 lambda 函数(这只是我想到的第一个概念)。你可以举一个例子,使用 map 和 lambda 来让一组数字变为原先的两倍。

numbers = [1, 2, 3, 4]
squares = map(lambda x: x * x, numbers)

我觉得这个示例不是真实的,有如下两方面的原因:

  • 将一组数字作平方运算不是在真实的程序中完成的事,除非是欧拉项目或某种东西(更多的可能是针对列表的操作)
  • map 在 Python 中并不常用,即便是做这个我也更愿意写 [x*x for x in numbers]

一个更加真实的 Python lambdas 的示例是使用 sort 函数,就像这样:

children = [{"name": "ashwin", "age": 12}, {"name": "radhika", "age": 3}]
sorted_children = sorted(children, key=lambda x: x['age'])

但是这个示例是被精心设计的(为什么我们需要对这些孩子按照年龄进行排序呢?)。所以我们如何来做一个真实的示例呢?

如何让你的示例真实起来:看你所写实际代码

我认为最简单的来生成一个例子的方法就是,不是凭空出现一个例子(就像我用那个儿童的例子),而只是从真正的代码开始!

举一个例子吧,如果我要用 sort.+key 来编写一串 Python 代码,我会发现很多我按某个标准对列表进行排序的真实例子,例如:

  • tasks.sort(key=lambda task: task['completed_time'])
  • emails = reversed(sorted(emails, key=lambda x:x['receivedAt']))
  • sorted_keysizes = sorted(scores.keys(), key=scores.get)
  • shows = sorted(dates[date], key=lambda x: x['time']['performanceTime'])

在这里很容易看到一个规律——这些基本是按时间排序的!因此,你可以明白如何将按时间排序的某些对象(电子邮件、事件等)的简单实例轻松地放在一起。

现实的例子有助于“布道”你试图解释的概念

当我试图去解释一个想法(就好比 Python Lambdas)的时候,我通常也会试图说服读者,说这是值得学习的想法。Python lambdas 是如此的有用!当我去试图说服某个人 lambdas 是很好用的时候,让他想象一下 lambdas 如何帮助他们完成一项他们将要去做的任务或是以及一项他们以前做过的任务,对说服他会很有帮助。

从真实代码中提炼出示例可能需要很长时间

我给出如何使用 lambdasort 函数的解释例子是十分简单的,它并不需要花费我很长时间来想出来,但是将真实的代码提炼出为一个独立的示例则是会需要花费很长的时间!

举个例子,我想在这篇文章中融入一些奇怪的 CSS 行为的例子来说明创造一个奇怪的案例是十分有趣的。我花费了两个小时来解决我这周遇到的一个实际的问题,确保我理解 CSS 的实际情况,并将其变成一个小示例。

最后,它“仅仅”用了 五行 HTML 和一点点的 CSS 来说明了这个问题,看起来并不想是我花费了好多小时写出来的。但是最初它却是几百行的 JS/CSS/JavaScript,它需要花费很长时间来将所有的代码化为核心的很少的代码。

但我认为花点时间把示例讲得非常简单明了是值得的——如果有成百上千的人在读你的示例,你就节省了他们这么多时间!

就这么多了!

我觉得还有更多关于示例可以去讲的——几种不同类型的有用示例,例如:

  • 可以更多的改变人的思维而不是直接提供使用的惊喜读者的示例代码
  • 易于复制粘贴以用作初始化的示例

也许有一天我还会再写一些呢? :smiley:


via: https://jvns.ca/blog/2021/07/08/writing-great-examples/

作者:Julia Evans 选题:lujun9972 译者:zepoch 校对:turbokernel

本文由 LCTT 原创编译,Linux中国 荣誉推出

相关内容

华为盘古团队否认开源模型抄...
智通财经获悉,近日,有消息指,华为盘古大模型涉嫌抄袭阿里巴巴通义千...
2025-07-07 16:14:44
浙大揭秘:为什么开源AI在...
这项由 浙江大学和蚂蚁集团联合实验室的朱雨琪、张宁宇等研究人员开展...
2025-06-27 18:41:01
速递|谷歌“终端智能体”的...
图片来源:谷歌 谷歌正在推出一款新型 AI Agent工具,旨在...
2025-06-27 13:12:21
最强Cursor开源替代方...
下载地址:https://github.com/voidedito...
2025-06-25 20:11:31
AI编程再突破,首个多智能...
曾经有着较高技术门槛的编程,正随着AI技术的普及加速成为人人可用的...
2025-06-24 17:13:18
微软 Win11 Linu...
IT之家 6 月 20 日消息,在今年 5 月的微软 Build ...
2025-06-21 13:12:08

热门资讯

Helix:高级 Linux ... 说到 基于终端的文本编辑器,通常 Vim、Emacs 和 Nano 受到了关注。这并不意味着没有其他...
使用 KRAWL 扫描 Kub... 用 KRAWL 脚本来识别 Kubernetes Pod 和容器中的错误。当你使用 Kubernet...
JStock:Linux 上不... 如果你在股票市场做投资,那么你可能非常清楚投资组合管理计划有多重要。管理投资组合的目标是依据你能承受...
通过 SaltStack 管理... 我在搜索Puppet的替代品时,偶然间碰到了Salt。我喜欢puppet,但是我又爱上Salt了:)...
Epic 游戏商店现在可在 S... 现在可以在 Steam Deck 上运行 Epic 游戏商店了,几乎无懈可击! 但是,它是非官方的。...
《Apex 英雄》正式可在 S... 《Apex 英雄》现已通过 Steam Deck 验证,这使其成为支持 Linux 的顶级多人游戏之...
如何在 Github 上创建一... 学习如何复刻一个仓库,进行更改,并要求维护人员审查并合并它。你知道如何使用 git 了,你有一个 G...
2024 开年,LLUG 和你... Hi,Linuxer,2024 新年伊始,不知道你是否已经准备好迎接新的一年~ 2024 年,Lin...
什么是 KDE Connect... 什么是 KDE Connect?它的主要特性是什么?它应该如何安装?本文提供了基本的使用指南。科技日...
Opera 浏览器内置的 VP... 昨天我们报道过 Opera 浏览器内置了 VPN 服务,用户打开它可以防止他们的在线活动被窥视。不过...