The lack of comments and function and variable name shorthand makes reading difficult

[wdfk-prog]

• My English level is not good, in the process of reading source code, the shorthand of functions and variables caused me reading trouble. Do you have any plans to change or comment on the shorthand?

example:

static int lfs_bd_read(lfs_t *lfs,
        const lfs_cache_t *pcache, lfs_cache_t *rcache, lfs_size_t hint,
        lfs_block_t block, lfs_off_t off,
        void *buffer, lfs_size_t size) {
}

• Functions have no comments and variable names have no explanation. As a result, I don't understand what the bd of bd_read means. I understand it as block device; The other is hint, which is even more confusing.This one is a prediction, right? Or threshold? Before looking at the code I understood it as the predicted size; Read the source code to understand as a threshold

[geky]

Hi @wdfk-prog, noted. There is a saying that naming things is one of the 3 hard problems in computer science.

It wouldn't hurt to add a glossary of terms, some of these don't even exist outside of littlefs (mdir, gstate, etc). Having one document with descriptions of everything is a good idea.

---

As for specifically hint, I think you might have been more correct with your first guess?

When you do a read with a cache, you can either read strictly the amount that fills the buffer, or read as much as possible in case of future read requests. Combining multiple reads into one reduces the number of bus transactions and can improve throughput, but if we read data that goes unused we're just wasting bus cycles.

hint controls this by allowing upper layers to specify how much they plan to read. Though it is a only a heuristic may not match the actual read pattern.

lfs_dir_fetch, for example, uses the largest hint possible (block_size), because we don't know where an mdir's log ends until after we parse it.

[wdfk-prog]

当您使用缓存进行读取时，您可以严格读取填充缓冲区的数量，也可以在将来出现读取请求时尽可能多地读取。将多个读取合并为一个可以减少总线事务的数量并提高吞吐量，但如果我们读取未使用的数据，我们只是在浪费总线周期。

Thank you for your reply

[geky]

If it's ok with you, keeping this open would be useful for tracking the idea of adding a glossary (GLOSSARY.md?).