diff --git a/README.md b/README.md
index d45ce68..c06ab1d 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ to the original author for a clean, focused implementation.
 I forked it because I wanted to pass label highlight attributes directly to
 `setup()` (instead of having to define a separate highlight group and re-apply
 it on every colorscheme change). I submitted that as a
-(PR)[https://github.com/yorickpeterse/nvim-jump/pull/8] but it was declined,
+[PR](https://github.com/yorickpeterse/nvim-jump/pull/8) but it was declined,
 which is the maintainer's right — the upstream plugin is explicitly considered
 feature-complete.
 
@@ -43,6 +43,13 @@ cursor-proximity sorting, and two-char labels for overflow matches, this fork is
 slightly _smaller_ than upstream — and an order of magnitude smaller than every
 other alternative on this list.
 
+### A note on style
+
+The code is intentionally dense. Comments are thorough by design — they do the
+explanatory work that would otherwise be done by helper functions and verbose
+names. If you're reading or editing `lua/tiny-jump/init.lua`, read the comments
+first. Don't "clean them up" — they're the docs.
+
 ## Requirements
 
 - Neovim 0.11.0 or newer.
diff --git a/lua/tiny-jump/init.lua b/lua/tiny-jump/init.lua
index 5e0cbe6..268f546 100644
--- a/lua/tiny-jump/init.lua
+++ b/lua/tiny-jump/init.lua
@@ -5,6 +5,11 @@
 -- This Source Code Form is subject to the terms of the Mozilla Public
 -- License, v. 2.0. If a copy of the MPL was not distributed with this
 -- file, You can obtain one at http://mozilla.org/MPL/2.0/.
+--
+-- Style note: this file is intentionally dense (126 SLOC in one file).
+-- Comments are thorough by design — they do the explanatory work normally
+-- done by helper functions and verbose names. If you're editing here, read
+-- the comments first.
 
 local api, fn, M = vim.api, vim.fn, {}