Poet Ponders the Digital

As I was writing a post about "comments" in computer programming source code, I noted that I like comments and marginalia when I write for "human" readers. Even when writing for myself, I like to preserve my notes. One of the things we lose with the transition from paper to digital media is the marginalia and other marks readers and writers leave as they read and write. Reading and Marking My wife and I both love books. We revere books. Because of this respect for the printed page, neither of us is an active highlighter, annotator, or scribbler. When I took a class that required marking in a book, it pained me to be destroying the pages with green and orange highlights. When I buy a book, especially a textbook, I don't want someone's marks on the pages. First, the previous reader(s) might have marked the wrong passages as important. Second, it is distracting. I want to read and think about a text on my own, at least initially. I do take notes, and I...

I like comments in computer programming source code. I've never been the programmer to claim, "My code doesn't need comments." Maybe it is because I've always worked on so many projects that I need comments  to remind me what I was thinking when I entered the source code into the text editor. Most programmers end up in a similar situation. They look at a function and wonder, "Why did I do it this way?" Tangent : I also like comments in my "human" writing projects. One of the sad consequences of moving to digital media is that we might lose all the little marginalia authors and editors leave on manuscript drafts. That thought, the desire to preserve my notes, is worthy of its own blog post — so watch for a post on writing software and notes. Here are my rules for comments: Source code files should begin with identifying comments and an update log. Functions, subroutines, and blocks of code should have at least one descriptive comment. ...