diff --git a/shsub.sh b/shsub.sh
index ec0e221..c40c2f6 100644
--- a/shsub.sh
+++ b/shsub.sh
@@ -1,4 +1,11 @@
 #!/bin/sh
+#
+# the user interface of shsub <https:/github.com/dongyx/shsub>
+# piping the output of tc to shell
+#
+# tokens surrounded by `__`, like `__version__`
+# is intended to be substituted at building time
+# using a macro processor like m4 .
 
 set -e
 tc="$(dirname "$0")/tc"
diff --git a/tc.c b/tc.c
index 9137da9..59e4691 100644
--- a/tc.c
+++ b/tc.c
@@ -1,3 +1,12 @@
+/* tc - compile the shell template to a shell script
+ *
+ * the shell template is read from stdin
+ * the shell script is printed to stdout
+ *
+ * tc is a component of the shsub project
+ * <https://github.com/dongyx/shsub>
+ */
+
 #include <stdlib.h>
 #include <string.h>
 #include <stdio.h>