sha1 hashes

examples.txt

@@ -56,7 +56,7 @@ Sorting by Functions
 # Random Numbers
 # Number Parsing
 # URLs
-# SHA1 Hashes
+SHA1 Hashes
 # Base64 Encoding
 # Reading Files
 # Writing Files

examples/sha1-hashes/sha1-hashes.go

@@ -1,28 +1,37 @@
+// SHA1 hashes are frequently used to compute short
+// identities for binary or text blobs. For example, the
+// [git revision control system](http://git-scm.com/) uses
+// SHA1s extensively to identify versioned files and
+// directories. Here's how to compute SHA1 hashes in Go.
+
 package main
 
-// Package `crypto/sha1` computes SHA1 hashes.
+// Go implements several hash functions in various
+// `crtypo/*` packages.
 import "crypto/sha1"
 import "encoding/hex"
 import "fmt"
 
 func main() {
-    // The pattern is `sha1.New()`, `sha1.Write(bytes)`,
+    s := "sha1 this string"
-    // then `sha1.Sum([]byte{})
+
+    // The pattern for generating a hash is `sha1.New()`,
+    // `sha1.Write(bytes)`, then `sha1.Sum([]byte{}).
+    // Here we start with a new hash.
     h := sha1.New()
 
-    // `Write` expects bytes. If you have a string `s`
+    // `Write` expects bytes. If you have a string `s`,
-    // use `[]byte(s)` to coerce it.
+    // use `[]byte(s)` to coerce it to bytes.
-    h.Write([]byte("sha1 this string"))
+    h.Write([]byte(s))
 
-    // Get the result. The argument to `Sum` can be used
+    // This gets the finalized hash result as a byte
-    // to append to an existing buffer: usually uneeded.
+    // slice. The argument to `Sum` can be used to append
+    // to an existing byte slice: it usually isn't needed.
     bs := h.Sum(nil)
 
     // SHA1 values are often printed in hex, for example
-    // with git.
+    // in git commits. Use `hex.EncodeToString` to convert
+    // a hash results to a hex string.
+    fmt.Println(s)
     fmt.Println(hex.EncodeToString(bs))
 }
-
-// You can compute other hashes using a similar
-// pattern. For exmpale, to compute MD5 hashes
-// import `crypto/md5` and use `md5.New()`.

examples/sha1-hashes/sha1-hashes.sh

@@ -1,2 +1,14 @@
+# Running the program computes the hash and prints it in
+# a human-readable hex format.
 $ go run sha1-hashes.go
+sha1 this string
 cf23df2207d99a74fbe169e3eba035e633b65d94
+
+
+# You can compute other hashes using a similar pattern to
+# the one shown above. For exmpale, to compute MD5 hashes
+# import `crypto/md5` and use `md5.New()`.
+
+# Note that if you need cyrtograhpically secure hashes,
+# you should carefully research
+# [hash strength](http://en.wikipedia.org/wiki/Cryptographic_hash_function)!