apiDoc 可以通过文本生成体验良好的 API 文档页面，这些文本可以以注释的形式放在代码里，apiDoc 读取源码注释，就可以生成页面了，当然也可以与代码分开，写一些全是注释的文档，作为 apiDoc 生成文档页面的「源文件」。 ...

摘录了一些内容，跟这些内容在书中出现的顺序不同，打散又整理了一下。除了斜体字部分，都是对原书的引用。 应该有的态度 程序员遵从不了解混乱风险的经理的意愿，也是不专业的做法。 做好自己的事，尊重自己的手艺，写干净的代码。 糟糕的代码引发混乱！别人修改糟糕代码时，往往会越改越烂。 碰到过“从跟上就烂”的项目代码，对这种项目的改造往往较为困难，成本很高，甚至不如推到重来。 签入的代码，要比签出时整洁一点。 代码应当讲述事实，不引人猜测。 整洁的代码总是看起来像是某位特别在意它的人写的。 聪明程序员和专业程序员之间的区别在于，专业程序员了解：明确是王道。 言到意到。意到言到。 如果同一段代码反复出现，就表示某种想法未在代码中得到良好的体现。 一些细节做法 （变量名的）名称长短与其作用域大小相对应。 变量声明应尽可能靠近其使用位置。 调用者应该尽可能放在被调用者上面。 应该避免我们的代码过多地了解第三方代码中的特定信息。依靠你能控制的东西，好过依赖你控制不了的东西，免得日后受它控制。 使用第三方库时，跟第三方库”划清界线“。一个可行的做法是把第三方库提供的接口再封装一层。业务代码只有自己的这层封装打交道，这样一来，如果要换用其他库，只改这个封装层，以此减少跟第三库的耦合以及依赖。 看到注释掉的代码，就删掉它。 否定式要比勘定式难明白一些。所以，尽可能将条件表示为肯定形式。 函数 函数的第一规则是要短小。第二条规则是还要更短小。 函数应该做一件事。做好这件事。只做这一件事。问题在于很难知道那件该做的事是什么。 要确保函数只做一件事，函数中的语句都要在同一抽象层级上。 在这个函数里做的事情，是同一个抽象层上的步骤，那么这个函数是只做了一件事。 函数越短小、功能越集中，就越便于取个好名字。 函数要么做什么事，要么回答什么事，但二者不可得兼。 错误处理 最好把 try 和 catch 代码块的主体部分抽离出来，另外形成函数。 函数应该只做一件事。错误处理就是一件事。因此，处理错误的函数不该做其他事。这意味着，如果关键字 try 在某个函数中存在，它就该是这个函数的第一个单词，而且在 catch/finally 代码块后面也不该有其他内容。 错误处理很重要，但如果它搞乱了代码逻辑，就是错误的做法。 测试 没有测试的代码不干净。 不可测试的系统不可验证。不可验证的系统，绝不应部署。 紧耦合的代码难以编写测试。 编写测试引致更好的设计。 写测试能够反过来逼着人写出更好的代码。 测试消除了对清理代码就会破坏代码的恐惧。 整洁的测试有什么要素？有三个要素：可读性，可读性和可读性。在单元测试中，可读性甚至比在生成代码中还重要。 独立测试应该相互独立。某个测试不应为下一个测试设定条件。 让测试具有表达力并短小精悍。

推荐一篇文章，原文链接 中国人思维的五大逻辑缺陷，BBC用一部趣味纪录片给解决了，里面讲到的 BBC 纪录片：《逻辑的乐趣》。 文中讲的五大逻辑缺陷： 概念模糊 不懂集合概念 类比推理，生拉硬扯 非黑即白，二元思维 乱立靶子，错误推理 春节期间，有没有跟亲戚朋友吵架的，八成跟这几个问题有关。 ...

最近读了大名鼎鼎的《原则》，硬着头皮读了一半，放弃。以后可能会重读，也可能不会，这里留下一点记录，算是为以后的重读体验提供一个对照。 整体的阅读体验很差，「个人经历」这一部分似乎是在讲一件事：请你把我看作投资界的乔布斯，虽然我没有那么他那么伟大。我们学过“摆事实，讲道理”这么一个说法，这本书呢，第一部分算是摆事实，偶尔讲个道理，第二部分，99% 是讲道理，想象一下如果是一个人在你前面不停地说理，这有多恐怖。 ...

当 Ubuntu 处于休眠状态时，可以通过直接插在电脑上的键盘唤醒，不能通过由蓝牙连接的鼠标唤醒。由于最近换了一款由电脑内置的蓝牙模块连接的键盘（不用蓝牙接收器）。Ubuntu 休眠时，蓝牙模块自然不工作，而我那蓝牙鼠标是由蓝牙接收器连接的，所以，我开始想方设法用这个蓝牙鼠标唤醒休眠的 Ubuntu。 ...

北京时间 10 月 9 号晚上 11 点，Google 开了场发布会，发布的产品有一款带屏幕的智能音箱 Google Home Hub，然后是一款安装了 Chrome OS 的平板电脑，最后是两款 Pixel 手机。最近几年我没看过什么发布会的直播，Google 的这一场我抱着期待的心情去看了，结果让我感到有点遗憾，甚至有点气愤。 ...

国庆假期没有出去玩，几乎就待在家里了。 时间统计 按照每天睡 8 小时来算，去掉睡觉时间，总共的活动时间是 112 小时。RescueTime 统计到了大概 50 个小时，这是我用手机和电脑的时长。WakaTime 统计了 8 小时 32 分，这是我写代码的时长。Toggl 统计了 12 小时 46 分，这是我写代码、看书、查找线上问题时记录的总时长。 ...

本文介绍三个在不同方面做时间追踪和统计的工具，让你知道自己每天用电脑和手机时都把时间花在了什么地方，有多长时间在做某个项目，有多少时间在写某种语言的代码……这三个工具分别是 RescueTime，Toggle 和 Wakatime。 ...

HTTP 的 POST 请求通常是用于提交数据，可以通过这篇文章来了解各种提交方式：四种常见的 POST 提交数据方式。做 Web 后端开发时，不可避免地要自己给自己发请求来调试接口，这里要记录的内容是如何使用命令行工具 curl 来进行各种方式的 POST 请求。 ...

这本书是 37signals 公司出的，英文原名是 Remote: Office Not Required，仅仅是因为 37signals 之前出过一本书 Rework，译名《重来》，这本 Remote 被牵强地赋予这样一个中文名《重来2》，算不上是译名。 ...