5 ms·

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

139 points by AbyCodes 15y ago

nitrogen 15y ago
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 (http://gcc.gnu.org/onlinedocs/cpp/Once_002dOnly-Headers.html#Once_002dOnly-Headers http://gcc.gnu.org/onlinedocs/cpp/Once_002dOnly-Headers.html...).
- comex 15y ago
  Yep, which states > The result is often thousands of needless lines of code passing through the lexical analyzer, which is (in good compilers) the most expensive phase. If only...
- 16s 15y ago
  Is he saying that the ifndef to protect against double/multiple includes should be in the file you don't want to include multiple times? The way that part is worded seems a bit confusing.
  - js2 15y ago
    I think he's saying this: #ifndef some_header #include some_header #endif
- apaprocki 15y ago
  The more modern gcc handling is with "#pragma once": http://en.wikipedia.org/wiki/Pragma_once http://en.wikipedia.org/wiki/Pragma_once His comments on include files are not the way the world has gone. In all my years writing C, I have never seen a C/C++ header which does not include the other headers it needs in order to compile cleanly. He states: "Simple rule: include files should never include include files." If you can find me one C project out there which has headers with zero #includes and forces each compilation unit including the header to include all the prerequisites needed for that header I would be genuinely interested. Even all OS header files include their pre-requisites and it is considered a bug if they do not do so. A more modern 21st century rule would be: "Simple rule: include file order does not matter. Use include guards (or #pragma once) and always include only the prerequisites needed to cleanly compile and nothing more."
  - luriel 15y ago
    > If you can find me one C project out there which has headers with zero #includes and forces each compilation unit including the header to include all the prerequisites needed for that header I would be genuinely interested. A whole OS does this: Plan 9 from Bell Labs :) For details see the paper by Rob Pike: How to Use the Plan 9 C Compiler http://doc.cat-v.org/plan_9/4th_edition/papers/comp http://doc.cat-v.org/plan_9/4th_edition/papers/comp Also the Plan 9 libraries are much cleaner and leaner than those in 'modern' *nix systems, which makes keeping track of includes much easier: http://man.cat-v.org/plan_9/2/intro http://man.cat-v.org/plan_9/2/intro
    - apaprocki 15y ago
      Well it stands to reason that the Plan 9 code would work that way if Rob Pike made the comment. I'm just wondering if anyone else found this way of coding attractive. Everything I've seen points to "no".
      - 4ad 15y ago
        Dennis Ritchie, creator of C? Ken Thompson, creator of Unix?
      - catwell 15y ago
        There is even a relatively popular piece of software dedicated to helping developers use this style: http://code.google.com/p/include-what-you-use/ http://code.google.com/p/include-what-you-use/
        apaprocki 15y ago
        That is not the stated purpose of the tool (to write code in the aforementioned style): "Include what you use" means this: for every symbol (type, function variable, or macro) that you use in foo.cc, either foo.cc or foo.h should #include a .h file that exports the declaration of that symbol. I agree 100% with that statement. According to the style, foo.h can never #include anything.
avar 15y ago
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. 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.
- bcl 15y ago
  The problem with doing it that way is that someone who comes across a checkout of your code will have no documentation. Think about the case of a distributed tar.bz2 or having a python application installed on your system. I prefer to have the comments in the code, in a form that can be used to generate documentation on the side (eg. doxygen, epydoc, etc.) so that they can't get lost, and so that you can read them as you read the code. It is difficult to re-combine the git commit messages with the code, but not hard to extract the comments from the code to create documentation.
- hndl 15y ago
  You're likely to cause a lot of trouble for other (possibly new) engineers going through your code. It seems cumbersome to look up metadata side-by-side while going through code. I, personally, always reread my code in the form of sentences. Something along the lines of: "okay, first I create a x. Then I pass y to it. I then set this flag..." If at any point I hesitate or have trouble stating what a line of code does, I add these sentences as comments so someone else can understand easily/quickly (if I can't alter the code for some reason, that is).
- jberryman 15y ago
  That's sounds interesting. I'm a bit of a git newb; what git commands or tools do you use to make this convenient?
  - MatthewPhillips 15y ago
    git commit :) Which is required before pushing any code.
huskyr 15y ago
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.
- dextorious 15y ago
  I can see how loop indexes (i) etc are nice to be short, but I don't see how the other stuff is valid, as opposed to a personal preference. Why is maxval a better name than MaximumValueUntilOverflow? The first lacks some extra information that I need to keep in mind every time I re-read that part of the code. And while the potential of overflow might be obvious, how about: minValueForTemperature instead of minval?
  - adbge 15y ago
    My variables are a little more verbose than the anemic style preferred by Rob Pike and used throughout K&R but, in that tradition, I also tend towards shorter, simpler variable names than something like minValueForTemperature, so maybe it would be useful to illuminate my own thinking. Complex variable names ought to be avoided because, simply, they hammer the programmer with a bunch of information every time they are used. Usually, when reading code, you're trying to wrap your head around how a procedure operates rather than the specifics of what it's operating on. Often, if you need to know more about what a variable represents, it's sufficient to refer to its declaration. Thusly, I prefer to name my variables so that one can pick up the general idea of what they're for from the name and then I document any additional information at the variable's declaration, either using a comment or via the type system. So, this is how I'd handle your examples: int maxval; /* until overflow */ Temperature minval;
  - nitrogen 15y ago
    If you're dealing with temperatures, a better name than minval or minValueForTemperature might be mintemp, min_temp, or minTemp depending on your style. One reason to use moderately short variable names is so that reading the name is faster. Include the most important information in the name, infer the rest from context. If you find you still need a lot of context, drop something less important from the name (e.g. minval->mintemp). I'd also avoid putting prepositions into variable names, but that's just a personal preference for keeping things to one adjective plus one noun where possible (less parsing overhead for my brain).
theorique 15y ago
Pointers are sharp tools, and like any such tool, used well they can be delightfully productive, but used badly they can do great damage Nice physical metaphor. Pointers are ... pointy.
zmj 15y ago
These style guidelines correspond exactly to idiomatic Go. I'm impressed how well Pike executed on his philosophy.
jbellis 15y ago
Many of these are elaborated on in the more recent (1999) "The Practice of Programming." Excellent book. http://www.amazon.com/Practice-Programming-Brian-W-Kernighan/dp/020161586X http://www.amazon.com/Practice-Programming-Brian-W-Kernighan...
now 15y ago
Ah, here’s that “I eschew embedded capital letters in names; to my prose-oriented eyes, they are too awkward to read comfortably. They jangle like bad typography.” comment I’ve been looking for. It seems he changed – or someone forced him to change – his mind on this in Go.
falcolas 15y ago
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. 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. 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?
- tptacek 15y ago
  That's idiomatic C code. You're right that it's not particularly readable if you aren't a C programmer, but if you came to a job interview and couldn't grok it immediately, I'd write "facility with C: marginal" in my notes.
  - falcolas 15y ago
    Missed this back closer to when you posted it - but it's less that I don't understand what's going on, and more that this code is more likely to go wrong & be harder to debug than more descriptive code. Just the other day, I was trying to identify what was being done by someone's "idiomatic" code, and had to keep three vertical screen's worth of data up just to follow what was happening. All that code was wrong, but because they were using pointers "idiomatically", it took a long time to find their off-by-one error. Granted, they had gone about 4 levels further with pointers than the given example in the article, but the premise is similar.
halayli 15y ago
Those notes found their way to 'The Practice of Programming' book. I highly recommend it.

139 points by AbyCodes 15y ago

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 (http://gcc.gnu.org/onlinedocs/cpp/Once_002dOnly-Headers.html#Once_002dOnly-Headers http://gcc.gnu.org/onlinedocs/cpp/Once_002dOnly-Headers.html...).

comex 15y ago
Yep, which states > The result is often thousands of needless lines of code passing through the lexical analyzer, which is (in good compilers) the most expensive phase. If only...
16s 15y ago
Is he saying that the ifndef to protect against double/multiple includes should be in the file you don't want to include multiple times? The way that part is worded seems a bit confusing.
- js2 15y ago
  I think he's saying this: #ifndef some_header #include some_header #endif
apaprocki 15y ago
The more modern gcc handling is with "#pragma once": http://en.wikipedia.org/wiki/Pragma_once http://en.wikipedia.org/wiki/Pragma_once His comments on include files are not the way the world has gone. In all my years writing C, I have never seen a C/C++ header which does not include the other headers it needs in order to compile cleanly. He states: "Simple rule: include files should never include include files." If you can find me one C project out there which has headers with zero #includes and forces each compilation unit including the header to include all the prerequisites needed for that header I would be genuinely interested. Even all OS header files include their pre-requisites and it is considered a bug if they do not do so. A more modern 21st century rule would be: "Simple rule: include file order does not matter. Use include guards (or #pragma once) and always include only the prerequisites needed to cleanly compile and nothing more."
- luriel 15y ago
  > If you can find me one C project out there which has headers with zero #includes and forces each compilation unit including the header to include all the prerequisites needed for that header I would be genuinely interested. A whole OS does this: Plan 9 from Bell Labs :) For details see the paper by Rob Pike: How to Use the Plan 9 C Compiler http://doc.cat-v.org/plan_9/4th_edition/papers/comp http://doc.cat-v.org/plan_9/4th_edition/papers/comp Also the Plan 9 libraries are much cleaner and leaner than those in 'modern' *nix systems, which makes keeping track of includes much easier: http://man.cat-v.org/plan_9/2/intro http://man.cat-v.org/plan_9/2/intro
  - apaprocki 15y ago
    Well it stands to reason that the Plan 9 code would work that way if Rob Pike made the comment. I'm just wondering if anyone else found this way of coding attractive. Everything I've seen points to "no".
    - 4ad 15y ago
      Dennis Ritchie, creator of C? Ken Thompson, creator of Unix?
    - catwell 15y ago
      There is even a relatively popular piece of software dedicated to helping developers use this style: http://code.google.com/p/include-what-you-use/ http://code.google.com/p/include-what-you-use/
      - apaprocki 15y ago
        That is not the stated purpose of the tool (to write code in the aforementioned style): "Include what you use" means this: for every symbol (type, function variable, or macro) that you use in foo.cc, either foo.cc or foo.h should #include a .h file that exports the declaration of that symbol. I agree 100% with that statement. According to the style, foo.h can never #include anything.

avar 15y ago

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. 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.

bcl 15y ago
The problem with doing it that way is that someone who comes across a checkout of your code will have no documentation. Think about the case of a distributed tar.bz2 or having a python application installed on your system. I prefer to have the comments in the code, in a form that can be used to generate documentation on the side (eg. doxygen, epydoc, etc.) so that they can't get lost, and so that you can read them as you read the code. It is difficult to re-combine the git commit messages with the code, but not hard to extract the comments from the code to create documentation.
hndl 15y ago
You're likely to cause a lot of trouble for other (possibly new) engineers going through your code. It seems cumbersome to look up metadata side-by-side while going through code. I, personally, always reread my code in the form of sentences. Something along the lines of: "okay, first I create a x. Then I pass y to it. I then set this flag..." If at any point I hesitate or have trouble stating what a line of code does, I add these sentences as comments so someone else can understand easily/quickly (if I can't alter the code for some reason, that is).
jberryman 15y ago
That's sounds interesting. I'm a bit of a git newb; what git commands or tools do you use to make this convenient?
- MatthewPhillips 15y ago
  git commit :) Which is required before pushing any code.

huskyr 15y ago

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.

dextorious 15y ago
I can see how loop indexes (i) etc are nice to be short, but I don't see how the other stuff is valid, as opposed to a personal preference. Why is maxval a better name than MaximumValueUntilOverflow? The first lacks some extra information that I need to keep in mind every time I re-read that part of the code. And while the potential of overflow might be obvious, how about: minValueForTemperature instead of minval?
- adbge 15y ago
  My variables are a little more verbose than the anemic style preferred by Rob Pike and used throughout K&R but, in that tradition, I also tend towards shorter, simpler variable names than something like minValueForTemperature, so maybe it would be useful to illuminate my own thinking. Complex variable names ought to be avoided because, simply, they hammer the programmer with a bunch of information every time they are used. Usually, when reading code, you're trying to wrap your head around how a procedure operates rather than the specifics of what it's operating on. Often, if you need to know more about what a variable represents, it's sufficient to refer to its declaration. Thusly, I prefer to name my variables so that one can pick up the general idea of what they're for from the name and then I document any additional information at the variable's declaration, either using a comment or via the type system. So, this is how I'd handle your examples: int maxval; /* until overflow */ Temperature minval;
- nitrogen 15y ago
  If you're dealing with temperatures, a better name than minval or minValueForTemperature might be mintemp, min_temp, or minTemp depending on your style. One reason to use moderately short variable names is so that reading the name is faster. Include the most important information in the name, infer the rest from context. If you find you still need a lot of context, drop something less important from the name (e.g. minval->mintemp). I'd also avoid putting prepositions into variable names, but that's just a personal preference for keeping things to one adjective plus one noun where possible (less parsing overhead for my brain).

theorique 15y ago

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

zmj 15y ago

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

jbellis 15y ago

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

now 15y ago

Ah, here’s that “I eschew embedded capital letters in names; to my prose-oriented eyes, they are too awkward to read comfortably. They jangle like bad typography.” comment I’ve been looking for. It seems he changed – or someone forced him to change – his mind on this in Go.

falcolas 15y ago

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. 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. 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?

tptacek 15y ago
That's idiomatic C code. You're right that it's not particularly readable if you aren't a C programmer, but if you came to a job interview and couldn't grok it immediately, I'd write "facility with C: marginal" in my notes.
- falcolas 15y ago
  Missed this back closer to when you posted it - but it's less that I don't understand what's going on, and more that this code is more likely to go wrong & be harder to debug than more descriptive code. Just the other day, I was trying to identify what was being done by someone's "idiomatic" code, and had to keep three vertical screen's worth of data up just to follow what was happening. All that code was wrong, but because they were using pointers "idiomatically", it took a long time to find their off-by-one error. Granted, they had gone about 4 levels further with pointers than the given example in the article, but the premise is similar.

halayli 15y ago

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