preconditions

When good comments mean bad language

I’ve had an epiphany.

For years, I’ve urged developers to write better comments. I still claim that’s a good idea (a very good one), but as I’ve pondered what a better programming language might look like, I’ve come to an important conclusion:

A lot of “best practice” commenting is just workarounds for inadequate language design.

This might seem like a crazy or arrogant claim. The Wirths and Matsumotos and Hejlsbergs and van Rossums and McCarthys of the world are incredibly smart people; how could I claim to know something that they do not? Each of these language designers has probably forgotten more about computer science than I will ever learn.

And yet, I think Randall Munroe (the cartoonist at xkcd) was right to make fun of our industry’s facile assumption that context-free grammar is all you need to know about formal language:

image credit: xkcd.com

To show you what I mean, I’ve inlined snippets of code from a variety of programming languages below. Don’t worry about digesting them carefully right now, but give them a quick glance and then move on to my analysis, and see if you agree with my claim about an unhealthy pattern. Continue reading →

Headers, babies, and bathwater

I claim that by eliminating the C/C++-style dichotomy between headers and implementation, most modern programming languages have thrown out the baby with the bathwater.

Don't throw out the baby with the bathwater! Photo credit: StubbyFingers (Flickr)

Don’t throw out the baby with the bathwater! Photo credit: StubbyFingers (Flickr)

If that sounds crazy, just hang with me for a minute.

I know my claim runs counter to popular wisdom; have a look at this thread on stackoverflow.com. Designers of languages like python and go and D and ruby and java consider it a feature that developers don’t have two redundant pictures of the same functionality. This comment from the C# 5.0 specification is typical:

“Because an assembly is a self-describing unit of functionality containing both code and metadata, there is no need for #include directives and header files in C#. The public types and members contained in a particular assembly are made available in a C# program simply by referencing that assembly when compiling the program” (p 3).

I agree.

Sort of…

Bad headers are a royal pain

It can be onerous to maintain the parallelism between a .h and a .cpp. And most C/C++ headers are managed so poorly that the benefits you might claim for them are theoretical rather than real. Three common antipatterns that I particularly detest: Continue reading →

// Comments on Comments

/*

We spend little or no time teaching programmers how to write good comments.

This is surprising, when you consider how often “total lack of comments” or “poor comments” are cited as evidence that certain modules (or the programmer who wrote them) are the worst thing that ever happened to the technoverse.

Comments shouldn’t leave you–or anybody else–mystified. :-) Image credit: xkcd

I happen to think that there are much yuckier tech things than poor or missing comments in code. But I still think our general level of comment proficiency is lower than it should be.

Here is my attempt to raise the bar a little.

Why We Comment

Sooner or later, most interesting programming problems require a sophisticated mental model of a problem. Building these models is hard work, and once we have them, we are paid to share with our team (or our future selves).

The best way to share mental models with other engineers is Continue reading →