http://www.cs.rutgers.edu/~pxk/rutgers/notes/content/Cstyle.pdf

http://www.csl.cornell.edu/courses/ece314/tutorials/pike_C.html

Picture above is Rob Pike and Brian Kernighan.

"I tend to err on the side of eliminating comments, for several reasons. First, if the code is clear, and uses good type names and variable names, it should explain itself. Second, comments aren't checked by the compiler, so there is no guarantee they're right, especially after the code is modified. A misleading comment can be very confusing. Third, the issue of typography: comments clutter code."

...

"...basically, avoid comments." --Rob Pike

And this quote is priceless garbage:

"Some output filtering programs “pretty-print” your source to look like an Algol-68 report, rendering all the reserved keywords in boldface and comments in italics. Rob Pike points out that this accentuates irrelevant detail and is as sensible as putting all prepositions in English text as bold type." --Paul Krzyzanowski

My thoughts:

Hmmm.. you know someone's being using UNIX too long when...

If comments clutter code, then document the code separately. If there is that big of a comment that you need to write, then make a separate readme file or document the code with developer documentation. Don't avoid commenting the source code! Rob Pike's advice is ridiculous.

I suspect that Rob is trying to "get revenge" on old standard Pascal and Algol by trying to do everything opposite to Algol and Pascal - his comments about syntax highlighting and everything about his and Paul's articles give off this bad smell. The bad smell I detect is that they are not rational, they are just out for revenge.

Since Algol and Pascal could be used for teaching, obviously commenting source code and prettying up source with syntax highlighting was prevalent in those languages and those times - so magically that means C code shouldn't have any source comments, or as little as possible. And since good software is documented well, I guess C code and C applications shouldn't be documented? Program obvious, no need for documentation! Program obvious, no need for source comments either!

Comments are useless, so are books

The other funny thing is, sometimes the guys who recommend not commenting source code are the same folks that have a few books for sale that they want you to buy.

One can always move the source comments out of the code and into developer documentation and readme files and man pages later - or you could write a book about your code and remove all the comments so more people buy your closed book. One can just delete comments if they are no longer needed. If source comments can become obsolete (which they can), so can user documentation and developer documentation. API documentation can become obsolete. Is that an excuse to not write any documentation, because documentation becomes obsolete? The reality is, comments can be updated, just like documentation. A combination of source comments and documentation is the best practice. Using Rob's advice is the wrong practice.

Assembly code is Self Documenting

"There is a style of programming that believes that every line of source code should have a comment associated with it. This is simply nonsense. When programming, you should assume that your program will be read in the future by someone versed in the language and basic algorithms." --Paul Krzyzanowski

Not every line of source needs to be commented, true. However, "basic algorithms" are far from what we see in complex software applications. If you are writing a hello world program, no need to comment the source since it shows how the hello world program works pretty precisely. For larger projects where pages and pages of code are written, there are two options:

1. lots more comments need to be added in the most clean way possible, precise comments, and if the comments get too big then move them to a readme file
2. developer documentation needs to be created (not user documentation, developer documentation)

If there is plenty of documentation on what the source does and what the application does, then the comments can be lessened - however most programmers are too lazy to write developer documentation on the code and algorithms. People write books on algorithms and this is accepted - but commenting source is bad? I don't see the logic there. In fact, we could argue that MAN PAGES are self explanatory and never need to be commented on, nor does USENET or mailing lists serve any purpose since THE SOURCE CODE or the MAN PAGES are self explanatory. See Smart Answers.

Philosopher once said: ask Rhetorical Questions

If there are plenty of programming books out there which comment on and address programming, how can one imply that source code is self explanatory?

Why would books and books and books after books need to be written on programming, and why would articles after articles after articles need to be written on programming, if most code and algorithms are self explanatory?

Why would there be books written with algorithms inside them, considering that the comments in the books take up more space than the algorithms? Why not just fill a book full of algorithms instead of including prose with the algorithms?

Why does Rob Pike write books when code is self explanatory?

Why does Kernighan sell books on algorithms in C and unix programming, if the algorithms and programming are supposedly self explanatory?

Why does Paul Krzyzanowski teach courses on C programming if C code is self explanotory?

Are lectures/books/courses not forms of source comments?

Does Paul Krzyzanowski write comments on the chalk board/felt board when describing code to his students? Why if they are self explanatory? Why have students sign up for courses if code doesn't need lecturing/commenting on?

In the real world, not many programmers are genius enough to just download the source code into their heads and magically know exactly what is going on. Skimming it over first and reading the comments along with scanning some of the algorithms really helps get a general glimpse of what is going on. Especially in C where it is typical for programmers to over use pointers to pointers.

Genius still needs hints

It is better to document your source code and comment it, and write books on it if you have time, than it is to make assumptions that we are all genius. Most people don't have time to document their source code - they just have time for comments. That is the reality. Most people don't have time to write books on their source code, they just have time for comments. If you ever needed to migrate and move the comments out of the source code and into documentation or into a book or an article, then you could do that later if you did comment the source. But if you didn't you are out of luck.

There shouldn't be comments under the Hood

Manuals? Who needs manuals - geniuses can figure out the program without a manual or comments anywhere - the program is self explanatory.

Syntax Highlighting is for Wimps

"Some output filtering programs “pretty-print” your source to look like an Algol-68 report, rendering all the reserved keywords in boldface and comments in italics. Rob Pike points out that this accentuates irrelevant detail and is as sensible as putting all prepositions in English text as bold type." --Paul Krzyzanowski

Again, I suspect that Paul is trying to "get revenge" on old standard Pascal and Algol by trying to do everything opposite to Algol and Pascal just for the sake of it with no logical reasoning.

Since when does programming have anything to do with English? You can't compare the two side by side. Just because reading a novel or a book with multicolored letters scattered across the book is ugly, doesn't make syntax highlighting in source code ugly! In year 2007, almost EVERYONE uses syntax highlighting and benefits from it. Does this mean that we should syntax highlight novels and books.. i.e. make certain words BOLD and others RED IN COLOR and others BLUE in color? No it does not. English has nothing to do with programming languages and source editors. Making conclusions by relating programming to english makes no sense. That's like saying because WOMEN can get away with wearing bras, men should be able to get away with it too - since we are both equal and we are both human.

Source code highlighting helps code, and it helps coders. Paul's comments aren't just outdated comments - they are truly ignorant comments and irrational and illogical conclusions.

Ask any programmer in year 2007 if he appreciates an editor with source code highlighting. One could argue that times change and that technology changes - but I could argue that if syntax highlighting looks good today it looked good back then too - people just didn't utilize it since they were ignorant or didn't have the processing power back then to afford syntax highlighting tokenizers (or didn't have color screens or good screen fonts).

Programming is not english. Just because a bunch of bold words in this sentence doesn't help me read the sentence easier, that does not mean that a programmer will automatically not benefit from syntax highlighting. It is an irrational conclusion based in invalid evidence. It is the same scare tactic they use when they say functions_with_uscores are superior to TheseFunctions since underscores are more like spaces in English text. That's like saying that since FRENCH FRIES taste better WITH SALT, we should add dots and periods all over our source code.. so that our source code will be more like FRENCH FRIES. May I ask what the hell French Fries and English Novels have to do with systems programming?

"I eschew embedded capital letters in names; to my prose­oriented eyes, they are too awkward to read comfortably. They jangle like bad typography." --Rob Pike

Underscores jangle across the screen and are in an awkward position on qwerty keyboards and offer the similar disadvantages of BiCapitalization. Combining the benefits of both is sometimes ugly but even practical in some situations, such as when a suffix needs to be added to a function. Religous lowercase underscoring means one cannot tell a function suffix from the main function, such as FunctionMain_special versus function_main_special. So is it a "function main" special, or is it a function "main special"?

Religiously using lowercase code with lowercase_underscore naming is just being religious for the sake of "getting revenge" on old standard Pascal. Double clicking BiCapitalized words in source documentation and in editors is easier, since the mouse will select the function.

Underscores space the code out and can be more readable if one considers his source code an Essay. Other programmers don't consider their programs Essay's and consider them programs. Eyes can easily get used to BiCapitalization. Saying that code should be written like prose is the same as saying Syntax Highlighting is useless since prose doesn't contain any syntax highlighting.

Neither underscores or BiCapitalization are superior, and code is not prose.

Since functions have names, it could be argued that functions should be named like Humans since Humans' have First and Last names with Capital Letters. What do people have to do with functions? What does prose have to do with functions? Not much. Anyone can come up with all sorts of ridiculous reasons for using either underscores or bicapitalization... just as Rob Pike comes up with ridiculous reasons as to why syntax highlighting is useless (even though the majority of people use syntax highlighting in 2007).

Summary

See also