February 28, 2017 3:47 PM

Comments on Comments

Over the last couple of days, a thread on the SIGCSE mailing list has been revisiting the well-tilled ground of comments in code. As I told my students at the beginning of class this semester, some of my colleagues consider me a heretic for not preaching the Gospel of Comments in Code. Every context seems to have its own need for, and expectations of, comments. Wherever students end up working, both while in school and after graduation, their employers will set a standard and expect them to follow. They will figure it out.

In most of my courses, I define a few minimal standard, try to set a good example in the code I give my students, and otherwise don't worry much about comments. Part of my example is that different files I give them are commented differently, depending on the context. A demo of an idea, a library to be reused in the course, and an application are different enough that they call for different kinds of comments. In a course such as compiler development, I require more documentation, both in and out of the code. Students live with that code for a semester and come to value some of their own comments many weeks later.

Anyway, the SIGCSE thread included two ideas that I liked, though they came from competing sides of the argument. One asserted that comments are harmful, because:

They're something the human reader can see but the computer can't, and therefore are a source of misunderstanding.

I love the idea of thinking in terms of misunderstandings between humans and the computer.

The other responded to another poster's suggestion that students be encouraged to write comments with themselves in mind: What would you like to know if you open this code six months from now? The respondent pointed out that this is unreasonable: Answering that question requires...

... a skill that is at least on par with good programming skills. Certainly new CS students are unable to make this kind of decision.

The thread has been a lot of fun to read. I remain mostly of the view that:

  • It's better to write code that says what it means and thus needs as few comments as possible. This is a skill students can and should work on all the time time.

  • If the code is likely to conflict with the expectations of the people most likely to read your code, then add a comment. This part depends a lot on context and experience. Students are just now earning their experience, and the context in which they work changes from course to course and job to job.
Students who care about programming, or who come to care about it over time, will care (or come to care) about comments, too.

Posted by Eugene Wallingford | Permalink | Categories: Software Development, Teaching and Learning

February 23, 2017 4:08 PM

Surrounding Yourself with Beginners

This comment at the close of a recent Dan Meyer post struck close to home:

I haven't found a way to generate these kinds of insights about math without surrounding myself with people learning math for the first time.

I've learned a lot about programming from teaching college students. Insights can come at all levels, from working with seniors who are writing compilers as their first big project, through midstream students who are learning OOP or functional programming as a second or third style, right down to beginners who are seeing variables and loops and functions for the first time.

Sometimes an insight comes when a student asks a new question, or an old question at the right time. I had a couple of students in my compiler course last fall who occasionally asked the most basic questions, especially about code generation. Listening to their questions and creating new examples to illustrate my answers helped me think differently about the run-time system.

Other times, they come while listening to students talk among themselves. One student's answer to another student's question can trigger an entirely new way for me to think about a concept I think I understand pretty well. I don't have any recent personal examples in mind, but this sort of experience seems to be part of what triggered Meyer's post.

People are always telling us to "be the least experienced person in the room", to surround ourselves with "smarter" or more experienced people and learn from them. But there is a lot to be learned from programmers who are just starting out. College profs have that opportunity all the time, if they are willing to listen and learn.

Posted by Eugene Wallingford | Permalink | Categories: Software Development, Teaching and Learning

February 19, 2017 10:42 AM

Bret Victor's Advice for Reading Alan Kay

In Links 2013, Bret Victor offers these bits of advice for how to read Alan Kay's writings and listen to his talks:

As you read and watch Alan Kay, try not to think about computational technology, but about a society that is fluent in thinking and debating in the dimensions opened up by the computational medium.
Don't think about "coding" (that's ink and metal type, already obsolete), and don't think about "software developers" (medieval scribes only make sense in an illiterate society).

I have always been inspired and challenged by Kay's work. One of second-order challenges I face is to remember that his vision is not ultimately about people like me writing programs. It's about a culture in which every person can use computational media the way we all use backs of envelopes, sketch books, newspapers, and books today. Computation can change the way we think and exchange ideas.

Then again, it's hard enough to teach CS students to program. That is a sign that we still have work to do in understanding programming better, and also in thinking about the kind of tools we build and use. In terms of Douglas Engelbart's work, also prominently featured among Victor's 2013 influences -- we need to build tools to improve how we program before we can build tools to "improve the improving".

Links 2013 could be the reading list for an amazing seminar. There are no softballs there.

Posted by Eugene Wallingford | Permalink | Categories: Computing

February 12, 2017 11:11 AM

Howard Marks on Investing -- and Software Development

Howard Marks is an investor and co-founder of Oaktree Capital Management. He has a big following in the financial community for his views on markets and investing, which often stray from orthodoxy, and for his straightforward writing and speaking style. He's a lot like Warren Buffett, with less public notoriety.

This week I read Marks's latest memo [ PDF ] to Oak Tree's investors, which focuses on expert opinion and forecasting. This memo made me think a lot about software development. Whenever Marks talks about experts predicting how the market would change and how investors should act, I thought of programming. His comments sound like the wisdom of an agile software developer.

Consider what he learned from the events of 2016:

  1. First, no one really knows what events are going to transpire.
  2. And second, no one knows what the market's reaction to those events will be.

Investors who got out of the market for the last couple of months of 2016, based on predictions about what would happen, missed a great run-up in value.

If a programmer cannot predict what will happen in the future, or how stakeholders will respond to these changes, then planning in too much detail is at best an inefficient use of time and energy. At worst it is a way to lock yourself into code that you really need to change but can't.

Or consider these thoughts on surprises (the emphasis in the original):

It's the surprises no one can anticipate that would move markets most if they were to happen. But (a) most people can't imagine them and (b) most of the time they don't happen. That's why they're called surprises.

To Marks, this means that investors should not try to get cute, predict the future, and outsmart the market. The best they can do is solid technical analysis of individual companies and invest based on observable facts about value and value creation.

To me, this means that we programmers shouldn't try to prepare for surprises by designing them into our software. Usually, the best we can do is to implement simple, clean code that does just what it does and no more. The only prediction we can make about the future is that we may well have to change our code. Creating clean interfaces and hiding implementation choices enable us to write code that is as straightforward as possible to change when the unimaginable happens, or even the imaginable.

Marks closes this memo with five quotes about forecasting from a collection he has been building for forty years. I like this line from former GE executive Ian Wilson, which expresses the conundrum that every designer faces:

No amount of sophistication is going to allay the fact that all of your knowledge is about the past and all your decisions are about the future.

It isn't really all that strange that the wisdom of an investor like Marks might be of great value to a programmer. Investors and programmers both have to choose today how to use a finite resource in a way that maximizes value now and in the future. Both have to make these choices based on knowledge gleaned from the past. Both are generally most successful when the future looks like the past.

A big challenge for investors and programmers alike is to find ways to use their experience of the past in a way that maximizes value across a number of possible futures, both the ones we can anticipate and the ones we can't.

Posted by Eugene Wallingford | Permalink | Categories: General, Software Development

February 10, 2017 3:55 PM

Follow-Up on Learning by Doing and Ubiquitous Information

A few quick notes on my previous post about the effect of ubiquitous information on knowing and doing.


The post reminded a reader of something that Guy Steele said at DanFest, a 2004 festschrift in honor of Daniel Friedman's 60th birthday. As part of his keynote address, Steele read from an email message he wrote in 1978:

Sussman did me a very big favor yesterday -- he let me flounder around trying to build a certain LISP interpreter, and when I had made and fixed a critical bug he then told me that he had made (and fixed) the same mistake in Conniver. I learned a lot from that bug.

Isn't that marvelous? "I learned a lot from that bug."

Thanks to this reader for pointing me to a video of Steele's DanFest talk. You can watch this specific passage at the 12:08 mark, but really: You now have a link to an hour-long talk by Guy Steele that is titled "Dan Friedman--Cool Ideas". Watch the entire thing!


If all you care about is doing -- getting something done -- then ubiquitous information is an amazing asset. I use Google and StackOverflow answers quite a bit myself, mostly to navigate the edges of languages that I don't use all the time. Without these resources, I would be less productive.


Long-time readers may have read the story about how I almost named this blog something else. ("The Euphio Question" still sets my heart aflutter.) Ultimately I chose a title that emphasized the two sides of what I do as both a programmer and a teacher. The intersection of knowing and doing is where learning takes place. Separating knowing from doing creates problems.

In a post late last year, I riffed on some ideas I had as I read Learn by Painting, a New Yorker article about an experiment in university education in which everyone made art as a part of their studies.

That article included a line that expressed an interesting take on my blog's title: "Knowing and doing are two sides of the same activity, which is adapting to our environment."

That's cool thought, but a rather pedestrian sentence. The article includes another, more poetic line that fits in nicely with the theme of the last couple of days:

Knowing is better than not knowing, but knowing without doing is as good as not knowing.

If I ever adopt a new tagline for my blog, it may well be this sentence. It is not strictly true, at least in a universal sense, but it's solid advice nonetheless.

Posted by Eugene Wallingford | Permalink | Categories: General, Personal, Teaching and Learning

February 09, 2017 4:25 PM

Knowing, Doing, and Ubiquitous Information

I was recently reading an old bit-player entry on computing number factoids when I ran across a paragraph that expresses an all-too-common phenomenon of the modern world:

If I had persisted in my wrestling match, would I have ultimately prevailed? I'll never know, because in this era of Google and MathOverflow and StackExchange, a spoiler lurks around every cybercorner. Before I could make any further progress, I stumbled upon pointers to the work of Ira Gessel of Brandeis, who neatly settled the matter ... more than 40 years ago, when he was an undergraduate at Harvard.

The matter in this case was recognizing whether an arbitrary n is a Fibonacci number or not, but it could be have been just about anything. If you need an answer to almost any question these days, it's already out there, right a your fingertips.

Google and StackExchange and MathOverflow are a boon for knowing, but not so much for doing. Unfortunately, doing often leads to a better kind of knowing. Jumping directly to the solution can rob us of some important learning. As Hayes reminds us in his articles, it also can also deprive us of a lot of fun.

You can still learn by doing and have a lot of fun doing it today -- if you can resist the temptation to search. After you struggle for a while and need some help, then having answers at our fingertips becomes a truly magnificent resource and can help us get over humps we could never have gotten over so quickly in even the not-the-so-distant past.

The new world puts a premium on curiosity, the desire to find answers for ourselves. It also values self-denial, the ability to delay gratification while working hard to find answer that we might be able to look up. I fear that this creates a new gap for us to worry about in our education systems. Students who are curious and capable of self-denial are a new kind of "haves". They have always had a leg up in schools, but ubiquitous information magnifies the gap.

Being curious, asking questions, and wanting to create (not just look up) answers have never been more important to learning.

Posted by Eugene Wallingford | Permalink | Categories: Computing, Teaching and Learning