Syntax highlighters are wrong (medium.com)

I don't think this explanation makes any sense. What was this person from the dark ages diffing against? Presumably, something on disk (i.e. something whose contents are recoverable).

Additionally, to me, red deletion doesn't mean "this was a bad action". It means "this was bad code, so we're crossing it out". Semantically, that makes total sense to me. Red is bad old code, green is new good code. Seeing a lot of red in code means the same to me as seeing a lot of red on a marked up copy of an essay (as long as it wasn't a professor who marked it up) -- I've identified a lot of improvements to make.

It also annoys me endlessly that words like 'var' and 'def' and 'function' get the brighest highlight, i know its a variable, it has a name, and i put it there.

However I don't understand why diff views abandon syntax highlighting. I understand there's sometimes a challenge of breaking up highlighting that depends on syntax that spans multiple lines, but it seems like we could do better than marking entire lines bright red and green and leaving the text black. This is the biggest thing that confuses me about Github - they've left it like this for years and it's probably the most looked-at part of their site.

http://youtu.be/z2exxj4COhU?t=16m6s

The biggest danger of comments (especially in heavily over-commented code) is that they can be misleading. If you get over used to relying on the comments as a true indication of what the code does, it's easy to be misled. It can especially cause you to miss subtle errors in the code (like an = instead of ==, or > instead of <).

Your eye should be drawn to the code first and foremost. Hence it is most important that it is formatted neatly and really, syntax highlighting is just a good way to catch typos quickly.

Comments should be what you read second, not what you read first. I.e., I just read this bit of code and it seems a bit weird, so I'll check the comment - oh yeah, now I understand what it's doing. Most comments should be ignored most of the time.

"we have collectively decided that the comment is less important than the code" - this is simply because the comment is less important than the code. Comments are not necessarily correct and don't always accurately represent what the code does. The code however, is always 100% accurate. That's why experienced programmers rely on the code first, comments second and try to avoid commenting ideas that can be expressed equally well in the code itself.

The use of Javadoc style comments is another strawman. As much as we might wish it were not necessary, using comments to generate documentation is actually useful. Similarly, having a coding standard requiring a comment block per class/function for the docs is also useful. A standardised structure is helpful when reading lots of code, and it helps delineate long source files, even if many of those comments turn out to be redundant. Having a highligher scream about all those comments being super important isn't helping by making people write more concise comments - it's merely trying to solve a problem that doesn't exist and creating a new problem in doing so.

Sometimes I need to comment something that really is super important like the example in the OP. It turns out, there's a way to do that which doesn't even rely on having any syntax highlighting whatsoever. You just write your comment like this:

  // !!!!! IMPORTANT WARNING !!!!! //
  // This does something really dangerous,
  // so don't change it unless you understand it...
  // !!!!! BEGIN CRITICAL SECTION !!!!! //
    if(foo) {
      bar();
    }
  // !!!!! END CRITICAL SECTION !!!!! //

A related rookie mistake that I see a lot is conflating the idea that less code = less complexity. Inexperienced programmers like to cram as much logic onto one line as possible, whereas better programmers often write the same thing as one-statement-per-line with a bunch of temporary variables, whose name encapsulates what each operation is doing. Which one do you think requires several lines of comments to explain what it does, and which requires no comments whatsoever? One has less code, but both have the same complexity. Except the one with more code breaks that complexity out into smaller, less complex individual chunks which makes reasoning about the whole much, much easier.

  //Set x to be 4
  x=5;

Seriously, to each his own. My IDEs all support customizable syntax highlighting to use whatever I want. They all ship with some default settings, but I mod them every time to support what works for me.

That's the correct answer -- whatever works best for the individual is what is "correct".

Also, the proposal that reviewers will determine whether or not to reject a patch based on how the colors look is preposterous. Imagine the Heartbleed patch being rejected because the colors look ugly. (This is, hilariously, the example the author uses.)

Also, the proposal that reviewers will determine whether or not to reject a patch based on how the colors look is preposterous. Imagine the Heartbleed patch being rejected because the colors look ugly. (This is, hilariously, the example the author uses.)

I could remap my colours, I suppose, however I used to often find myself trouble shooting at someone else's terminal. Since then I just found it easier to have it turned off completely.

1) Give the code clarity

2) Be the source of documentation

These goals aren't easily reconciled, too many comments reduce clarity whilst increasing the likelihood that they are inaccurate and not maintained.

Documentation generated from comments seldom explains how to use the APIs that a library or program exposes. Usually resulting in the addition of more comments, further reducing code clarity.

The real problem with comments is that too few of us write useful documentation.

I can't remember who said that the best thing a programmer can do is to learn to write.

Our job isn't just to write code, it's also to make sure the code is used... meaning we need to learn how to sell our code to people who will maintain and implement things against our interfaces. We need to sell to other devs, by documenting better and explaining how to use our code. Only then can we reduce the in-line comments that reduce readability of code.