Schools are terrible at the craft of software style stuff. The one time they did teach me about comments, they seemed to insist on something like seen in this s

Schools are terrible at the craft of software style stuff. The one time they did teach me about comments, they seemed to insist on something like seen in this story: http://thecodelesscode.com/case/39 http://thecodelesscode.com/case/39 I think there might actually be an old-school element here. Coding up to the 80s or the early 90s tended to be about squeezing the absolute most capability you can from the machine. Clarity and conciseness probably took the back seat to optimization hacks, so writing the comment to describe the original intent of the code actually was vital. Peter Norvig's old Lisp programming book has a nice illustration on how the programming style in Lisp has evolved from the 70s to the book's 1992: http://books.google.com/books?id=QzGuHnDhvZIC&lpg=PP1&dq=paradigms%20of%20artificial%20intelligence&pg=PA30 http://books.google.com/books?id=QzGuHnDhvZIC&lpg=PP1&#3... SICP also had the "programs must be written for people to read, and only incidentally for machines to execute" quip, and also notes "In this book we don't use many comments; we try to make our programs self-documenting by using descriptive names." Since the 90s, programmers have had a bit more breathing room, and the idea to actually write the code itself so that it will concisely describe what it's doing when read by a competent programmer has become much easier. You still want to document nontrivial interfaces, tricky things from the application problem domain and problem workarounds in the code, but the actual business-as-usual code tends to be readable and idiomatic enough that you don't need to comment every function, method and variable. Most can be inferred well enough from context.