Notes on Programming in C - Rob Pike, February 21, 1989

One thing I've changed about my style in the last few years is to almost never comment my code, but to instead write long and detailed Git commit messages explaining the how's and why of that code at the time that I write it.<p>That means that over time I effectively have comments for every line of code in the program, but it's associated metadata instead of being embedded inline, which means that the comments never go out of date, and their history is accurately tracked in version control.

Many of these are elaborated on in the more recent (1999) "The Practice of Programming." Excellent book. <a href="http://www.amazon.com/Practice-Programming-Brian-W-Kernighan/dp/020161586X" rel="nofollow">http://www.amazon.com/Practice-Programming-Brian-W-Kernighan...</a>

The one point that is notably less relevant today is the last section regarding include files. Gcc has a special case for a header file that is entirely wrapped in an #ifndef (<a href="http://gcc.gnu.org/onlinedocs/cpp/Once_002dOnly-Headers.html#Once_002dOnly-Headers" rel="nofollow">http://gcc.gnu.org/onlinedocs/cpp/Once_002dOnly-Headers.html...</a>).

These style guidelines correspond exactly to idiomatic Go. I'm impressed how well Pike executed on his philosophy.

<i>Pointers are sharp tools, and like any such tool, used well they can be delightfully productive, but used badly they can do great damage</i><p>Nice physical metaphor. Pointers are ... pointy.

Even though this is over 20 years old, many comments are still very valid. I especially like the section about short variable names and functions.

Those notes found their way to 'The Practice of Programming' book.<p>I highly recommend it.

Some absolutely fascinating points. However, I must admit that the portion on link pointers was, frankly, damned frightening as someone who could possibly have to come back and figure out what's really going on.<p>I'm reminded of Perl when I look at that link pointer code. It's succinct, easy to write, works great most of the time, and nearly impossible to go back and decode later. You simply require too much context to find the one place where you stepped beyond the array and into no-man's land.<p>I love pointers; I think that like other sharp tools, they have their uses. However, like other sharp tools, they require training and attention to use properly. Lots of people lose fingers to saws every year; how many brain cells have you lost to debugging pointer mistakes?