diff --git a/README.md b/README.md
index 9f5ce321..0384e088 100644
--- a/README.md
+++ b/README.md
@@ -9,14 +9,16 @@ just
 Commands are stored in a file called `justfile` or `Justfile` with syntax inspired by `make`:
 
 ```make
+build:
+    cc *.c -o main
+
+# test everything
 test-all: build
     ./test --all
 
+# run a specific test
 test TEST: build
     ./test --test {{TEST}}
-
-build:
-    cc *.c -o main
 ```
 
 `just` produces detailed error messages and avoids `make`'s idiosyncrasies, so debugging a justfile is easier and less surprising than debugging a makefile.
@@ -47,6 +49,7 @@ Recipes look like this:
 recipe-name:
     echo 'This is a recipe!'
 
+# this is a comment
 another-recipe:
     @echo 'Another recipe.'
 ```
diff --git a/justfile b/justfile
index 49874fea..f9a6122b 100644
--- a/justfile
+++ b/justfile
@@ -1,6 +1,7 @@
 test: build
 	cargo test --lib
 
+# only run tests matching PATTERN
 filter PATTERN:
 	cargo test --lib {{PATTERN}}