m07：名字、注释，以及先写注释

先列出几个候选词，再挑最精确的那个。total_ 记录的是日志文件的字节数；dead_ 记录的东西，在 STATS 输出里已经有一个更好的名字了。第 14 章说的一致性有三条：同一用途总用同一个名字、这个名字不用于别的用途、用途要窄到所有同名变量行为一致。

站在调用者的角度：一两句话说清它做什么；每个参数和返回值的精确含义（单位、范围、包含与否、"不存在"时是什么）；副作用；会抛什么异常、抛了之后数据处于什么状态。写到"失败后会怎样"时，回头仔细读一遍实现，注释必须是真的。compact() 在这里藏着一个惊喜。

写 exists() 的注释时，如果要写全，你会被迫写下一个奇怪的副作用；写 compact() 的失败语义时，你会写出一句很别扭的话。第 15 章说过：一个简单而完整的注释写不出来，往往说明设计本身有问题。这个任务里，把问题如实写下来就够了，别在这里修结构。

RENAME 可以用现有的 set 和 del 组合出来，日志里就是两条记录。两条记录的顺序决定了"在中间崩溃"时的结果：先删 src 再写 dst，崩溃后值就丢了；先写 dst 再删 src，崩溃后两个 key 都有值。真正原子的做法需要新的记录类型，要改日志格式。选哪种都行，但必须写进注释。

名字

接口注释

// Loops over index_ and writes each entry with a second LogWriter opened
// with O_TRUNC on path_ + ".compact", fsyncs it, closes writer_,
// rename(2)s the new file over path_, reopens writer_ with O_APPEND,
// then sets total_ to the new size and dead_ to 0.
void compact();

std::pair<bool, std::string> get(const std::string& key) const;
bool exists(const std::string& key) const;
void del(const std::string& key, const WriteOptions& wo);
std::string getRange(const std::string& key, int64_t start, int64_t end) const;

// Rewrites the log so that it holds only the current value of each key,
// which brings garbageBytes() to 0. Takes time proportional to the size
// of the live data. If the process dies during compaction, the old log
// is still complete. Throws std::runtime_error on I/O errors; the log on
// disk then still holds all the data, but if the failure happened while
// switching to the new file, every later write fails too until the Store
// is reopened.
void compact();

// Returns {true, value} if `key` is present and {false, ""} otherwise.
// Counts one keyspace hit or miss in stats().
std::pair<bool, std::string> get(const std::string& key) const;

// Returns whether `key` is present. Like get(), counts one keyspace hit
// or miss in stats().
bool exists(const std::string& key) const;

// Removes `key`. Throws KeyNotFound if it is absent.
void del(const std::string& key, const WriteOptions& wo);

// Returns bytes start..end of the value of `key`, both ends inclusive,
// counting from 0. Throws KeyNotFound if `key` is absent and
// std::out_of_range unless 0 <= start <= end < length of the value.
std::string getRange(const std::string& key, int64_t start, int64_t end) const;

类注释也补上了：Store 是什么、修改何时写入日志、写日志失败时内存和日志各处于什么状态、不是线程安全的。Database 不重复这些注释，只说一句"语义同 store.h 中的同名方法，另外每次写都可能触发压缩"。

注释暴露出来的设计问题

• compact() 的失败语义写不简单。本想写"失败时数据不变"，回头核对实现才发现：基线先关写端再 rename，rename 失败后所有写都会失败。注释只能写成那句别扭的话。这就是第 15 章说的金丝雀：注释难写，设计有问题。（m01 的 LogFile::rewrite 顺带修掉了它。）
• exists() 会改统计数据。写全了注释，这个副作用就摆到了明面上，GET 先 exists 再 get，一次命中计两次。m08 会处理它。
• Index::find() 的指针有效期原来只存在于作者脑子里，现在写进了 index.h。

实现注释：只写"为什么"

// write the record
writer_.append(rec, wo);

uint64_t size = kRecordHeaderSize + key.size() + value.size();
// update dead
const IndexEntry* old = index_.find(key);
if (old) dead_ += old->recordSize;
// update total
total_ += size;
// update index
index_.put(key, value, size);

// Log first: if the write throws, memory still matches the log.
writer_.append(rec, wo);

uint64_t size = kRecordHeaderSize + key.size() + value.size();
const IndexEntry* old = index_.find(key);
if (old) garbageBytes_ += old->recordSize;
logBytes_ += size;
index_.put(key, value, size);

RENAME：注释先行

// Gives the value of `from` to `to` and removes `from`, as if by
// set(to, value) followed by del(from). An existing value of `to` is
// replaced. Renaming a key to itself does nothing. Throws KeyNotFound if
// `from` is absent; nothing changes then.
// Not atomic across crashes: the change is logged as two records, so a
// crash between them leaves both keys holding the value after a restart
// (never neither).
void rename(const std::string& from, const std::string& to, const WriteOptions& wo);

真正原子的 RENAME 需要新的记录类型，要改日志格式和重放。参考答案没有做，而是把"不原子，但只多不少"写进接口。如果你写注释时觉得这句话无法接受，那正说明应该去改格式：注释在这里起了设计评审的作用。决定都做完了，实现只有几行：

void Store::rename(const std::string& from, const std::string& to, const WriteOptions& wo) {
    const IndexEntry* source = index_.find(from);
    if (!source) throw KeyNotFound(from);
    if (from == to) return;
    // Copy: set() may rehash the index and invalidate `source`.
    std::string value = source->value;
    // Write `to` before deleting `from`, so that a crash in between leaves
    // the value under both keys rather than under neither.
    set(to, value, wo);
    del(from, wo);
}

数字：store.h 从 62 行变成 116 行，其中注释从 6 行变成 49 行。

代价与取舍

审稿人仍会指出的问题

• get() 仍然返回 std::pair，exists() 的副作用只是被写明了、没有被去掉，Server::bulk(s, true, true) 的两个 bool 仍然看不出含义：m08。
• del、getRange 的错误情况本可以定义掉（m06）。注释越写越长的地方，往往就是设计可以更简单的地方。
• RENAME 的处理函数又复制了一遍参数检查和 try/catch：重复的问题见 m05。

完整讨论见 solutions/m07/DISCUSSION.md。对照自己的改动：

cd project            # 仓库里 minikv/ 和 solutions/ 所在的目录
make -C minikv clean && make -C solutions/m07 clean
diff -ru minikv solutions/m07
make -C solutions/m07 test