标签 示例 下的文章

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

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

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

好的示例是真实的

为了说明为什么好的案例应该是真实的,我们就先讨论一个不真实的案例。假设我们在试图解释 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中国 荣誉推出

我们中的许多人经常查看 man 页面 来了解命令开关(选项),它会显示有关命令语法、说明、细节和可用的选项,但它没有任何实际的例子。因此,在组合成一个我们需要的完整命令时会遇到一些麻烦。

你确实遇到这个麻烦而想要一个更好的解决方案吗?我会建议你试一下 cheat

Cheat 是什么

cheat 允许你在命令行中创建和查看交互式的 速查表 cheatsheet 。它旨在帮助提醒 *nix 系统管理员他们经常使用但还没频繁到会记住的命令的选项。

如何安装 Cheat

cheat 是使用 python 开发的,所以可以用 pip 来在你的系统上安装 cheat

pip 是一个与 setuptools 捆绑在一起的 Python 模块,它是在 Linux 中安装 Python 包推荐的工具之一。

对于 Debian/Ubuntu 用户,请使用 apt-get 命令apt 命令来安装 pip

[对于 Python2]
$ sudo apt install python-pip python-setuptools
[对于 Python3]
$ sudo apt install python3-pip

RHEL/CentOS 官方仓库中没有 pip,因此使用 EPEL 仓库,并使用 YUM 命令安装 pip

$ sudo yum install python-pip python-devel python-setuptools

对于 Fedora 系统,使用 dnf 命令来安装 pip

[对于 Python2]
$ sudo dnf install python-pip
[对于 Python3]
$ sudo dnf install python3

对于基于 Arch Linux 的系统,请使用 Pacman 命令 来安装 pip

[对于 Python2]
$ sudo pacman -S python2-pip python-setuptools
[对于 Python3]
$ sudo pacman -S python-pip python3-setuptools

对于 openSUSE 系统,使用 Zypper 命令来安装 pip

[对于 Python2]
$ sudo pacman -S python-pip
[对于 Python3]
$ sudo pacman -S python3-pip

pip 来在你的系统上安装 cheat

$ sudo pip install cheat

如何使用 Cheat

运行 cheat,然后按相应的命令来查看速查表,作为例子,我们要来看下 tar 命令的例子。

$ cheat tar
# To extract an uncompressed archive:
tar -xvf /path/to/foo.tar

# To create an uncompressed archive:
tar -cvf /path/to/foo.tar /path/to/foo/

# To extract a .gz archive:
tar -xzvf /path/to/foo.tgz

# To create a .gz archive:
tar -czvf /path/to/foo.tgz /path/to/foo/

# To list the content of an .gz archive:
tar -ztvf /path/to/foo.tgz

# To extract a .bz2 archive:
tar -xjvf /path/to/foo.tgz

# To create a .bz2 archive:
tar -cjvf /path/to/foo.tgz /path/to/foo/

# To extract a .tar in specified Directory:
tar -xvf /path/to/foo.tar -C /path/to/destination/

# To list the content of an .bz2 archive:
tar -jtvf /path/to/foo.tgz

# To create a .gz archive and exclude all jpg,gif,... from the tgz
tar czvf /path/to/foo.tgz --exclude=\*.{jpg,gif,png,wmv,flv,tar.gz,zip} /path/to/foo/

# To use parallel (multi-threaded) implementation of compression algorithms:
tar -z ... -> tar -Ipigz ...
tar -j ... -> tar -Ipbzip2 ...
tar -J ... -> tar -Ipixz ...

运行下面的命令查看可用的速查表。

$ cheat -l

进入帮助页面获取更多详细信息。

$ cheat -h

via: https://www.2daygeek.com/cheat-a-collection-of-practical-linux-command-examples/

作者:Magesh Maruthamuthu 译者:geekpi 校对:wxy

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