
Syntax highlighters are wrong (2014) - TuringTest
https://jameshfisher.com/2014/05/11/your-syntax-highlighter-is-wrong/
======
martin_a
> I have identified two important kinds of value judgment - important vs.
> unimportant, and success vs. failure. I have showed how these judgments are
> made by our existing code highlighting themes: comments are hidden as
> unimportant, and deletions are displayed as errors. These judgments intrude
> on and influence our own thoughts and judgments.

I find this whole article highly speculative. It's based on principles the
author adapted from somebody who wrote a book about how to write code, but I
doubt they really influence or apply to lots of people.

I don't value comments less or more because they are cursive or light grey.
Code highlighting should help to easily distinguish between different parts of
the code, but as unobtrusive as possible. This is not an easy task especially
with the limited set of options you have for plain text.

I also don't perceive removals in diff view as "bad" because they are red but
as "look here, could be important".

So this article is about the feelings of the author, not so much about facts.

~~~
onion2k
_I also don 't perceive removals in diff view as "bad" because they are red
but as "look here, could be important"._

That's really the problem with using red for deletes in a diff. Red implies
that the deleted lines are more important than the added lines, and that's
wrong. You shouldn't (and can't really) focus exclusively on the deleted code.
Breaking the 'red = important' connection and using a color scheme that gives
equal weight to the removed and added lines may well work better once you get
past how weird it is.

~~~
EForEndeavour
_> Red implies that the deleted lines are more important than the added lines_

I've never gotten that impression. I and my coworkers & classmates usually
highlight text using the standard _yellow_ highlighter, occasionally using
other snazzy highlighter colours - red sometimes included, but usually not.

The associations that leak in from other domains are green=good/go,
red=bad/stop. It's very easy to mentally remap the colours to the intuitive
green=new, red=old.

------
franciscop
> red means bad and green means good. This association is cross-cultural,
> probably universal, and probably as old as the hills

This is strongly and patently not true. Here in Japan the available taxi is in
Red while the taken one is in Green, and there are many more similar examples.
Admitedly it's mixed, because traffic lights are still red to stop and blue to
cross. Wait blue? There was no distinction in Japan between green and blue
back in the day and that still remains. Colors _are_ very much culture-
dependent, and saying otherwise is ingenuous at least and misleading at best.

~~~
EForEndeavour
You have a point that colour perception is culturally modulated, but I'd argue
that the original point still stands in the modern world (which is what's
relevant to the discussion of syntax highlighting): the majority of people who
look at code will sooner associate red with bad than with good, and this
association has become self-sustaining (much like the widespread adoption of
qwerty-like keyboards).

Your example of Japanese taxi signs using red to signal availability is an
interesting but rare exception to the general rule across the industrialized
world that red={warning, danger, no, stop, delete}, and green={safe, good,
yes, go, maximize}. For this example, there are many counterexamples. After
all, Japan uses red=stop, green-blue=go on all traffic lights, railways,
shipping, and aviation, in accordance with international conventions.

Yes, colours are very much culture-dependent, but red=bad and green=good (or
green-blue for cultures that don't distinguish these two colours) has been
intentionally adopted across cultures for generations -- dating back to
shipping and train signals, if not much earlier to verdant countrysides versus
blood, fire, etc.

~~~
HeavenFox
In Chinese stock market, Red means the stock is up and green means it’s down.
If you have an iPhone, try setting the language to Chinese and open the Stocks
app. Red has always been considered an auspicious color in Chinese culture.
It’s the theme color of weddings and Chinese New Year.

~~~
EForEndeavour
And what colour means stop/error in China's traffic lights, rail networks,
shipping lanes, and aircraft?

~~~
HeavenFox
That is not exactly relevant.

In China it is understood that red color is used to indicate STOP because it
has the greatest wavelength and is therefore more visible in inclement
weather.

In addition, color code for traffic light is fixed by international convention
and it’s not like China can choose whatever it wants.

My point is, culture has nothing to do with the choice of stop light color in
China

~~~
robocat
> In addition, color code for traffic light is fixed by international
> convention and it’s not like China can choose whatever it wants

China _can_ choose whatever they want, but don't.

Many countries have not signed the Vienna Convention on Road Signs and
Signals. For example China, Japan and the United States have not signed the
convention.

Japan is a good example: "It is a near universal constant when driving: red
means stop, and green means go. So fundamental is this dynamic that it is
codified in international law under the Vienna Convention on Road Signs and
Signals, which has been ratified by 74 countries. Why, then, does Japan — not
a signatory to the Convention —seem to buck the trend with its blue/green
traffic signals?" [https://www.atlasobscura.com/articles/japan-green-traffic-
li...](https://www.atlasobscura.com/articles/japan-green-traffic-lights-blue)

------
sacado2
In practice there are 3 types of comments:

\- documentation, that should be parsed by some external tool (javadoc, godoc,
etc.)

\- warnings in the code, like the "this call is very important because of..."
example from the article

\- commented out code.

I want warnings to sitck out, but I don't want doc to stick out.

Commented-out code should not exist, granted, but in the meantime I don't want
it to stick out either. If I'm commenting-out my own code, that's because I'm
trying to understand some issue, so please don't distract me. I'll remove it
later, I promise.

~~~
gitgud
> Commented-out code should not exist, granted .... I'll remove it later, I
> promise.

In my opinion, you should _never_ commit commented out code. Here's why:

1\. Commented out code, just confuses and clutters people's interpretation of
the project. It's meaning is not clear as it's not a functioning part of the
system.

3\. It can incorrectly inflate the apparent complexity of a project.

2\. It reduces the impact of _meaningful_ comments, so people end up ignoring
all comments.

Commit a _working-state_ of the system only. If you're working through a
problem, save the functions without commenting them out and completely remove
them when you don't need them... you can always go back and find it in the
source-control later when you need it.

Also, one of the first things I do when coming onto a new project is (switch
to a new branch) and remove all the dead code.

~~~
hibbelig
>> _Commented-out code should not exist, granted .... I 'll remove it later, I
promise._

> _In my opinion, you should never commit commented out code._

But the editor works on uncommitted code, too. GP doesn't want to be
distracted by that.

~~~
gitgud
_> ... so please don't distract me. I'll remove it later, I promise._

It could mean people are literally looking over his shoulder at his screen and
complaining. But to me, it implies that commented code is becoming part of the
project source...

~~~
sacado2
No, I'm talking about my own "private" code in my own editor. This is a
conversation with my editor while I'm "in the zone". I (usually) don't commit
commented-out code, for the reasons you mentioned above.

~~~
gitgud
Ah I see the context now, sorry for assuming the intent.

------
signal11
> red means bad and green means good. This association is cross-cultural,
> probably universal, and probably as old as the hills: red as blood, green as
> grass.

Red is a lucky/auspicious/'good' colour in China and parts of S/SE Asia. Red
dresses, for instance, are traditional at some cultures' weddings.

~~~
jimktrains2
Even in the US red isn't "bad". Examples being the red sports car, the
traditional colour of barns, Protestant church doors, power-on lights on
devices, red roses, and Valentine's day hearts.

I think the author is just conflating the commonality of traffic symbols as
some deep-rooted, cross cultural phenomena.

~~~
tomjakubowski
I'd also object to "stop", as in at a traffic like, connoting "bad". A break
from driving is often welcome!

------
ktpsns
The obvious problem is that comments have different semantics: They are used
for additional information -- this is what Javadoc or Python's embedded
documentation is for. Note that Javadoc (or Doxygen) solves this problem with
another syntax:

    
    
        /* regular comments */
        // regular comments
    
        /** Javadoc comments */
        /// Javadoc comments
    

This convention is understood by many syntax highlighters.

However, regular comments are frequently used to "comment out" code snippets
_while working on code_. I assume "graying out" follows the "commenting out"
idiom.

The colouring preferences of visual diff's are a completely different topic.
IMHO, red/green is just a widespread convention. Of course it mentally
supports the bad/good association, which is seldomly correct (even in other
contexts as code).

~~~
Gibbon1
I've come around to the idea that you should never comment out code, you
should use #if #endif. And if the code has been replaced then you should
include the new and old code as follows.

    
    
       // comment that explains what the change was and why we are keeping the old code around. 
       // Date we made this change.
       #if true 
          new code 
       #else 
          old code 
       #endif

~~~
ktpsns
That's a good idea, but it requires the language ecosystem to be shipped with
that kind of preprocessor. In the given examples (Java and Python), that's not
the case. And the proposal fails if you comment out non-compiling code without
the context switch to a preprocessor:

    
    
      if false:
         this(does not compile)
      else:
         that.might("be")

------
mcv
> _" Why, then, are we psychologically rewarding additions with green, and
> punishing deletions with red?"_

I see this the opposite. I love commits with tons of red, and dislike commits
with lots of green. Green means more reading and trying to figure out what
this new code does, whereas lots of red with a little green means someone cut
away all the old ugly code and replaced it with something better.

If the colours were to be reversed, I would get really confused. I guess I've
sufficiently internalised the current usage, and I'm fine with it. I suppose I
should ask a younger programmer how they view the red and green in commits.

Edit: His "neutral" addition/deletion colours don't really work for me. They
don't have the clear association that red/green has. And the red = bad, green
= good works fine if you want to remove bad code and add good code. It's never
that simple, obviously, but the colour work very well for me.

The colours don't work so well for red/green colour blindness, obviously.
That's a good reason to use something else. But maybe every highlighting tool
needs to be configurable to use the colours that work best for you. Most are,
but is github?

------
bschwindHN
Just change your damn color scheme to what you want and get on with the actual
work. They're not "wrong", you're just being dramatic.

------
taneq
The main thrust of this article seems to be more "crufty comments are wrong"
rather than "the syntax highlighter is wrong." (Although when I was a fresh
graduate my boss suggested setting comment colour to light grey to make it
easier to read the code... which it really did because 90% of the comments
were just commented-out lines of code from experiments that never got cleaned
up. _shudder_ )

For the diff colouring, I've always read red lines as being "bad" in the sense
of "these ones had to go" (not in the sense of "these changes are wrong") and
green lines being "good" in the sense of "these are what they should have
been."

~~~
ModernMech
Which is shame, because as many know who have written a syntax highlighter for
a language, there seem to be no real science or rules for what gets
highlighted and what doesn't; and which do colors do we apply for each? Do
operators get highlighted? What about function names? Variables? What about
parens? Do we give [ ( and { different colors? Some lisp highlighters give
each paren a different color so that it looks like a rainbow. Is this a good
idea or a bad one? Do we give + - * / the same colors? Any color at all? The
same color as =? It seems like everything is done based on intuition rather
than any methodology. I'd be interested to see an article that answers some of
the above questions.

------
ajross
> Martin writes that ‘the proper use of comments is to compensate for our
> failure to express ourself in code.’ It’s there to shout out about something
> that the code fails to tell you. The comment needs some help to distinguish
> itself from the surrounding code and say, ‘hey, I’m important!’

This is exactly backwards in my experience. Comments can lie. Computers don't
execute comments. When reading code for understanding, you need to treat the
comments as at best a guide and read the code first. Sure, there are rare
cases where an algorithm is so subtle it needs to be explained via other
media, but even then a simple link to documentation or a textbook reference is
IMHO a better guide. Comments are awful in practice. Stay away.

Whether that has anything to do with syntax highlighting is an open question.

~~~
kqr
On the other hand, one of the most common reasons for comments to lie is that
the code is updated and the comment is not. If comments were highlighted to
grab attention more strongly, perhaps that would happen less often.

~~~
0xffff2
Perhaps, but I rather doubt it. Despite the link's claims, comments _are_
noise for precisely the reason GP mentioned. Because comments can (and often
do) lie, I only ever read comments after I thoroughly understand what the code
is doing. If I already know why it's doing that thing, then the comment is
(for me in that moment) superfluous and I'm unlikely to want to bother paying
it any attention at all. As such, no matter how distracting you make the color
scheme for comments, my brain is eventually going to learn to filter them out
by default.

------
buro9
Was javadoc the first tool that encouraged, almost forced, the redundant
comment?

Instead of comments just to make clearer the intent of the code, now we had
highly repetitive comments in boilerplate format that would add nothing to
already clear code.

As comments went from being one thing "make intent clear, shout why something
happens" to multiple things "generate docs" \+ "pass commit linting"... the
value of a comment diminished fast and so it isn't surprising to me that
syntax highlighting downplays the comment.

What is surprising is that we haven't yet defined multiple types of comment: 1
for documentation, 1 for clarity. Or that we haven't determined the context of
a comment and chosen to highlight depending on that context.

~~~
ivanbakel
>What is surprising is ... we haven't determined the context of a comment and
chosen to highlight depending on that context.

My syntax highlighter _does_ do this, for every language I can think of - and
so does essentially every code editor software I can remember using. The most
popular editors even have the power to collapse doc comments, and I believe
some do by default.

------
kieckerjan
I have never cared much about syntax highlighting. I find it distracting,
especially when typing. Type opening quotes and your whole buffer turns
"stringy" until you type the closing quotes. It's enough to induce epileptic
seizures.

In my editor I switched off all my syntax highlighting except for two things:
all comments are in bold (for I agree with the author that comments should be
in your face) and comments marked with "TODO" are in pesky red, nudging me to
fix the marked issue ASAP.

~~~
spatulon
Similarly, I made a custom colour scheme that only highlights comments and
TODOs: [https://imgur.com/zp4GarX](https://imgur.com/zp4GarX)

I feel like my ability to read code improved from disabling any other
highlighting, but I have no real way of testing whether that's true.

~~~
Narishma
Is that 0x1_0000 a typo? Shouldn't it be 0x1_000 or 0x10_000 instead?

~~~
spatulon
Note that it's not my code, nor am I familiar with it. I just had it lying
around on my disk to try out Alacritty.

Here's the line in question:
[https://github.com/jwilm/alacritty/blob/master/alacritty_ter...](https://github.com/jwilm/alacritty/blob/master/alacritty_terminal/src/renderer/mod.rs#L499)

I agree 0x1_000 or 0x10_000 would make more sense, but it doesn't look like
the actual value used is hugely significant.

------
saagarjha
My syntax highlighter is not "wrong", it just doesn't match with the relative
importances that the author of this article has assigned each thing (of
course, using their cultural bias…).

------
Sharlin
The _real_ problem with red/green diffs is that up to 10% of men are red-green
colorblind. It's a real accessibility issue.

~~~
rocqua
Blue yellow is also a form right? What is a safe color blind-friendly pair of
contrasting colors?

~~~
pluma
Red and blue (like Jenkins, but that seems to be coincidental).

That said, if you think color accessibility is about picking the right
categories of colors you have a long way to go.

The important thing is that the colors need to have sufficient contrast beyond
mere hue. Light green and deep red is fine for me as a strong deutan (i.e.
severely green blind) even though there are combinations of "red" and "green"
that are practically indistinguishable for me.

~~~
rocqua
Hmm, red-and blue makes sense, given that they are the furthest apart
physically.

Obviously accessibility is about more than picking colors, but if a complaint
is 'this is a bad color pair' it is interesting to know what is a better pair.

As for contrast beyond hue, does that include saturation? Because keeping
luminance constant is an important part of keeping an interface legible.

I'd say a red-blue default with full configurability might be the best
approach.

~~~
Sharlin
Red and blue are not ”the furthest apart”. Red and cyan, or blue and yellow,
are complementary (180° separated on the color wheel). But color perception is
more complicated than that.

I believe something like orangish red and bluish green are distinct enough to
most people with a red-green deficiency (including myself). The difference in
”blue content” makes them distinguishable.

~~~
rocqua
The actual wave-lengths are the furthest apart. Whilst that is not
perceptually relevant, it is relevant to what happens when color-receptors
fail. That is, as long as you have two different color receptors that respond
differently to different wave-lengths, those will receive different signals
from red and blue light.

~~~
Sharlin
The wavelengths that are furthest apart are red and _violet_. Which
perceptually are close together, for red-green blind as well. But what does
matter is picking the colors based on the corresponding receptors' peak
sensitivity. The L receptors _are_ most sensitive to red, and the S receptors
to blue, so in that sense you're right. (Red-green blind or weak people lack
the M receptors of have anomalous versions, respectively.)

------
j0057
I associate the diff colors with traffic lights: red means "after applying
this commit, we STOP running this code..." and green means "...and we START
running that code".

No value judgement intended, and who doesn't love to see a diff with a ton of
red replaced with just a little green? Someone was cleaning house!

------
awinter-py
Comments are necessary for a million reasons and the people who argue against
them often haven't maintained someone else's code (or even their own).

A few: side effects, ordering that's required for correctness but not
checkable by the language, guarding performance tricks from getting deleted.

An unfamiliar person trying to find out where in the codebase a thing happens
relies on comments. Comments are much more readable and much more searchable
than functions, in the same way that blogposts and comments add semantic terms
to web documents to improve search.

Also intent -- to guide us in situations where 'this function is doing
undesirable things but I have no idea what it's supposed to do so I can't fix
it'.

Yes they get stale if not updated; it's a living spec. But most teams don't
update _any_ specs so code & comments are still the best one we have.

------
nnq
100%, I always tweak any color theme I use to have comments highly contrasting
green or orange... dunno what's with the modern trend of making everything
eyes-hurtingly-colourful, but then going and muting out the parts that should
stand out the most.

Another pet peeve I have is why tf do all color themes try to color variable
vs. functions vs. fields differently: they _never_ get this right in dynamic
languages, and they couldn't anyway bc variables often hold functions in them.

 _Basically all modern / editor-default color themes are dead wrong and
annoying!_

(VSCode and Visual Studio ones _may_ be on point occasionally, but they fail
at dynamic languages too and only end up spewing meaningless distracting
colors everywhere.)

~~~
chrismorgan
A few years back I decided to start a new colourscheme in Vim which I called
“bland”. It started out with reverting all of the colour and term portions of
syntax/syncolor.vim, and using black (#000) on white (#fff) (I had hitherto
used a dark colourscheme, but decided to try a light one), with keywords bold,
and that was it. After a week of that (a deliberately enforced delay), I
succumbed to adding a little bit of text colouring, #cc0000 for strings,
#009900 and italics for comments, and for no particularly good reason #0000cc
for numbers. I added pale background colouring for diffs too. It’s grown a
_very_ little more complex since then, but not much. I haven’t ever switched
back. I made a dark variant of it last year for the odd occasions where I want
a dark colourscheme. Then it’s primarily white on black.

Most colourschemes out there are _absurdly_ low-contrast. Part of my
inspiration in finally getting round to making this colourscheme, and going
for a light background, was experience several years earlier of using Vim on a
not-too-bright laptop on a bus with substantial sunlight: I always had to
switch to a dark-on-light colourscheme to be able to read the code at all.

------
jrockway
I agree about the diffs and have written the same thing myself. Deleting code
is good! Adding code is neutral, at best. (You get a new feature, of course...
but also new bugs!)

As for syntax highlighting, I'm not really sure what we want out of it. I like
it for typo protection; type "cnost" and it doesn't turn blue, fix it to
"const" and hey! pretty! It must be right. But it doesn't go far enough. If
you call "foo.bar()", Github turns "bar" blue, regardless of whether or not
it's possible to call "bar()" on "foo". My editor doesn't highlight those, but
it should; if the method is callable, make it pretty, if it's some made up
thing that isn't going to compile, make it ugly.

I think, at best, what we use syntax highlighting for is to break up what
seems like a monotonous large quantity of text. Kind of like how I started a
new paragraph to emphasize this point; it does help the reader. But I think we
could do way way better, it's just that people seem to have given up. I think
the excuse is along the lines of "it's too slow to use a 1970s era computer to
figure out what methods are available"; that's true, but we are not using
1970s computers anymore. Why are compilers or syntax analyzers so slow,
anyway? We can play real-time multiplayer games that render 240 snapshots of a
3D virtual world every second... but compiling hello world takes on the order
of 200ms. Seems strange. No wonder our tools are so bad. What we're doing must
be very hard for the computer.

(Github, however, has no excuse. They have all the time in the world to
produce good syntax annotations; it's not like you're typing new code into
that window. And their syntax highlighting does significantly worse than any
editor I've ever seen.)

------
pluma
I don't really have the patience for armchair psychologists arguing about the
meaning of colors in syntax highlighting anymore.

Red/green for deletion/insertion is less or more standard across tooling. It's
not a quirk of GitHub and if you're going to make an argument about it shaping
our value judgements about code contributions I'd like to see an actual paper
or study please.

As others have pointed out, comments can have a lot of different reasons to
exist. Inline documentation can be useful for tooling but should fade in the
background when looking at the code directly. Commented out code generally
should just be deleted but there are some rare circumstances where you might
want to leave it.

Since we're already deeply in "unfounded personal opinions presented as fact"
territory, I really prefer when important comments are explicitly marked using
a standard keyword like "NOTE", "WARNING", "FIXME" or "TODO" because editors
can be configured to highlight these lines differently, completely avoiding
this flaming mess of an argument.

------
Elte
Every time an article about comments comes around I wonder: am I the only one
who likes lots of comments, even those that don't add _any_ added reasoning,
if they provide a clear visual distinction between things? The "Damn right
it's ugly!" example from this article is infinitely more readable to me than
his suggested replacement.

~~~
Grumbledour
I agree with you. It's always easier to ignore comments than to not have them
and trying to figure out stuff. I vastly prefer a 100 line function with
comments every ten lines about what is to happen next to twenty, five line
functions with "great" names (they never are), that are sprinkled about the
whole file making the whole thing a case study in reinventing the goto
statement. Though it often seems many people consider the later to be "better"
and "self-documenting" code.

To be fair though, three line comments for every member seems a bit excessive
to me as well.

------
davedx
> Perhaps it’s not as pretty, but it’s more usable. [Edit: quite a few people
> disagree. I suggest it would take some time to retrain your eye.]

Yikes. That's probably not the best way to approach improving usability -
hectoring users that their interpretation is wrong.

------
galfarragem
Tonsky (Nikita Prokopov) view on syntax highlighting:
[https://www.youtube.com/watch?v=l1b7Da2DnPo&feature=youtu.be...](https://www.youtube.com/watch?v=l1b7Da2DnPo&feature=youtu.be&t=833)

------
bastawhiz
> quite a few people disagree. I suggest it would take some time to retrain
> your eye.

Or, the author is asserting that their approach is better without any real
evidence other than their own line of reasoning. There's a great deal of
arrogance in this post, like the assumption that red and green have universal
connotations (just look at the chart emoji to see a counterexample). Do
Japanese programmers have inherently better code because the existing
red/green semantics in Japan match up with the author's argument? Probably
not. It's an interesting couple of ideas but without meaningful data I
wouldn't consider making these changes.

------
scandox
I often write comments before I write the code as it helps me think it out.
Then I leave the comments there even when they are not necessarily
highlighting critical points. Often I find them a useful reminder later on.

I don't think I've ever looked at some code and thought I wish there were less
comments. I don't see why comments have such a lowly status. Of course you can
tell when someone wrote a comment because they felt they HAD to...stuff like:

    
    
        /* Adding one to X */
        x = x + 1
    

Which I've actually seen...but anything even remotely intelligent is generally
welcome, I think.

~~~
hnlmorg
Honestly, I find those kind of comment more distracting than useful.

I once read somewhere that comments should explain the reason rather than the
action. For example:

    
    
        /*
           x is taken from a system counter but it needs
           to be consumed by humans. So we add 1 because
           humans don't count from zero
        */
        x = x + 1
    

is a more useful comment.

~~~
lozenge
but pageCountDisplayed = pageCount + 1 is more useful still.

~~~
hnlmorg
In that specific case, potentially - bare in mind it's imaginary code you're
refactoring. There will be occasions when "ugly" code is required. The point
of my post, which I suspect you missed, is that comments will generally be
more useful if they describe the purpose of that code (which is harder to
deduce) rather than what that code does (which often can be easily deduced
just be reading the code).

~~~
lozenge
The point of my post is that code will be more useful if it describes the
purpose of that code. Sure, for the rest of the time there's comments.

~~~
hnlmorg
Yes, I got that. As I said:

> In that specific case, potentially - bare in mind it's imaginary code you're
> refactoring. There will be occasions when "ugly" code is required.

ie, I don't disagree with your point however it's not always possible to
refactor code for readability. Plus you're still missing the point that
writing better comments can give you additional information ("why does it do
it") that you might not gleam even from even well written code ("what does it
do").

------
codethief
I think the whole situation with comments is a lot more nuanced than the
author suggests. Namely, there aren't only the "important" and "redundant"
type of comments[1], so the whole discussion about making them more visible or
less visible is bound to be severely biased right from the start.

[1] The following (amazing) article discusses code comments at length:

[http://antirez.com/news/124](http://antirez.com/news/124)

------
kazinator
Fading out comments is exactly right. This choice in syntax highlighting is
correctly based on the observation of what the vast majority of comments _are_
, not what some blogger thinks ideal comments should be.

Important "must read me" comments can be accommodated in syntax coloring via
some additional notation:

    
    
       //
       // this is faded toward the background
       //
       // ! this is loud
       // ! read it!
       //
    

And, you know, unless I'm focusing on that area of the code for a specific
reason, I probably don't want to read that. Should I need to turn my attention
to that area of the code, I will read it, even if it is tastefully dimmed out.

One problem with a loudly colored comment is that there is no "marked read"
button once you get the message, like in a message inbox. No matter how many
times you read it, it stays lit up. (Maybe there should be such a feature. If
a browser can remember what links you have visited, and show them in a darker
color, a text editor could keep track of which loud comments you have already
read.)

------
necovek
As others have pointed out, choice of colours does not neccessarily convey the
message author insists on.

What's else, one could make a similar argument on the use of + (a good thing)
and - (a bad thing) to say that removals should be marked with +, and
additions with -. Maybe switch to sad and happy emoticons?

I am pushing it a bit just to make a point (because yes, + is even more
commonly used to indicate addition, and - to indicate substraction or, well,
removal). There is this whole science dedicated to making reading nicer, more
efficient and more comfortable, and we want none of it.

I think there are better ways to make code more readable in our editors than
changing a few colours.

Inspired by Knuth's literate programming renders of TeX and METAFONT source
code, I've experimented with variable-width fonts for code (why are we
programmers not allowed to read beautifully typeset text when everyone else
is?), but editors today are not really comfortable with that.

------
eterm
Comments are both important and distracting.

I immediately prefer the faded comments because they are there if I want to
read them. I'm not going to struggle to understand and reason about the
comments.

I may well find myself needing to re-read and reason about the code that
follows, so it's good that it's easier to follow the code without distraction.

------
alkonaut
It would be very easy for syntax highlighters to highlight things withing
comments (e.g. if I write a "IMPORTANT: blah" in a comment, that is
highlighted more than other comment text). There are editors that support
this.

~~~
djsumdog
Most of the JetBrains editors highly TODO in a bright color.

------
Shorel
This is a very opinionated and I would say personal issue.

I also think most syntax schemes (the highlighter is perfectly fine, let us be
technically correct) are very wrong for my own purposes.

This thing is the wrong colour, this looks like a candy party, some colours
should be used only for such and such thing, strings should always be this
colour, etc.

So, I made my own syntax colour scheme with my own conventions, and it is
great.

But I don't try to convince anyone to use my colour scheme. That would be
preposterous and intrusive.

------
hu3
Previous discussion (2014):
[https://news.ycombinator.com/item?id=7728781](https://news.ycombinator.com/item?id=7728781)

------
Kovah
I am currently reading Clean Code and there are so many useful hints in there,
comments being one of the thi gs that stuck in my head. Talking about syntax
highlighting, I edited my editor to treat @Todo and similar comment additions
in the same way as errors: they do not belong thete and should be fixed as
soon as possible. Marking them ass errors led to several small fixes. After
reading this article I might try the same with regular comments.

------
tobr
Related: please never use red to give me feedback on what I typed into your
form. It’s not dangerous if I have skipped filling out a field. And it’s
awkward because it’s not clear at what point you should “warn” me about it;
after all, the form usually starts out empty, and that’s not considered an
error.

By focusing on what I completed you give a much more helpful vibe, and you can
reserve red for destructive actions, like permanently deleting something.

------
codr7
I used to swear by syntax highlighting, but then I tried turning it off after
hearing of someone else who tried and never went back.

That was five years ago. It felt weird for about ten seconds. These days I
find code with syntax highlighting very noisy and almost impossible to deep
read.

It's quite possible that it was always like this, but that I was numbed to the
effects and lacked reference points.

Whatever the case, I don't miss it at all.

~~~
w56rjrtyu6ru
I also tried coding without syntax highlighting but it only lasted a few
months.

One of the downsides is that when you show your code to other developers who
don't have the necessary visual bandwidth, they get uncomfortable.

One of the few things syntax highlighting actually helps with is for catching
typos in keywords. (To the trained eye, this could be replaced with just
bolding or italicizing the keywords.)

Today I'm using "the colorful words" again (as non-technical associates have
described syntax highlighted code), and still looking for a syntax
highlighting theme which does not look like crap. (Gruvbox is the closest I've
gotten yet.)

Giving each identifier its own color (e.g. [https://medium.com/@evnbr/coding-
in-color-3a6db2743a1e](https://medium.com/@evnbr/coding-in-
color-3a6db2743a1e)) is another interesting idea.

------
sradman
I think this raises an important issue; some comments are important and it
would be helpful if they stood out as such. I disagree with the idea that
since SOME comments are important, therefore, ALL comments should stand out.
Others have pointed out how comments marked with TODO are treated differently
by syntax highlighters. I’m going to start prefixing my important comments
with NB (nota bene).

~~~
jgtrosh
Thanks for pointing out that NB doesn't denote minor comments (as I believed),
quite the opposite.

------
V-2
_> multiple people have suggested a different interpretation: old code bad,
new code good. However, since that would be a similarly invalid value
judgment, the argument below is still valid_

Well: if you regarded the removed code as _better_ than what you're replacing
it with, you wouldn't be committing these changes, right?

------
adamlett
I wrote a minimalist Textmate theme based on the same thinking, namely that
comments should stand out from the surrounding code. Check it out:
[https://github.com/KaptajnKold/Minimal](https://github.com/KaptajnKold/Minimal)

------
phodge
Comments are washed out because the compiler/interpreter will completely
ignore them. That's what your syntax highlighter is trying to tell you - that
these lines are unimportant because it they have literally no effect on the
program.

------
Snortibartfast
Instead of using colors in diffs, why not change the typography? Make removed
lines less visible, and added lines more visible, perhaps grey text for
removed and bold black for added?

------
gcoda
There is awesome plugin for VSCode, Better Comments. I disabled most of
highlighting in syntax, rainbow brackets and better comments is more than
enough

------
m3at
Note that vimdiff does use neutral colours by default.

------
yb71
I honestly don't see why discuss syntax hilighters. I mean, I like vim with
green comments and red operators, over black bg, and my neighbour uses x-emacs
with gray bg, no color coding but with some bold and italics. Why should we
care about each other's formatting? We never had issues with looking at each
other's screens. Btw, same goes for curly on the same line or the next.

------
rsl7
I love this article. Nice re-framing of color choices.

This makes me think it would be nice to have at least two functionally
distinct comment types: remarks (to be visually hilighted), and temporarily
disabled code (to be visually suppressed). I suppose comment lines (remarks)
and comment blocks (code) could be used for this, but as the author points out
this would need to be a widely adopted convention.

------
Quipunotch104
This article is from 2015.

~~~
ac42
It's a comment, it may be obsolete.

------
fourier_mode
TL;DR: OP doesn't like the colors used in common syntax highlighters.

And to that I say, change it. Editors these days are designed to make color-
scheme changing as easy as possible.(I can confirm this about vim, emacs,
sublime, Atom)

------
DarkWiiPlayer
I've never understood this idea that comments are only necessary because the
code is somehow flawed. This seems to be based on an ideal of beautiful code
that both tells the computer step by step what to do and at the same time
paints a bigger picture and expresses the intent of the programmer.

In reality though, code isn't poetry. C, Pascal, Javascript, etc. aren't meant
to convey the thoughts of the programmer, but to give a machine clear
instructions on what to do.

Humans aren't good at reading code. If we were, natural languages would have
evolved like that, but they haven't. The idea of writing code for a machine
and adding meta-information for humans to better understand the context isn't
a bad idea, it's efficient.

What's more, when your code really does perfectly convey the intentions of the
programmer and makes comments unnecessary, then your program is encoding
information that the computer doesn't need, in a format that makes it harder
for the computer to distinguish between relevant and irrelevant information.

~~~
rkangel
There are two sorts of comments - "What" comments and "Why" comments.

"What" comments tell you what the code is doing. In a lot of cases, depending
on the language, the need for these can be reduced by writing clear code. This
is much easier in, say, Python than Assembly. Even in Python though, sometimes
you can be doing something a bit subtle where a 2 line comment can clear
things up. These comments aren't irreplaceable because with a bit of reading
and work, you have all the information to work out what is happening.

"Why" comments are much more important - telling the reader WHY the code is
doing whatever it is that it's doing. The 'trim()' comment referenced in the
article is a great example of a Why comment - all the reading around the code
wouldn't give you an explanation (although sometimes git blame will).

Many 'what' comments are superfluous, almost no 'why' comments are - they are
the collective memory of design decisions that otherwise lives in people's
heads.

~~~
MaxBarraclough
This strikes me as a good, but incomplete, taxonomy of comments.

What about comments that describe our assumptions? I guess that's a special-
case of 'what' comments. Such comments are often better expressed as
assertions in code (i.e. adding _more_ code to improve readability, rather
than _reworking_ the code). Assertions have the considerable advantage that
they don't go stale as the code is changed.

> although sometimes git blame will

That's a great point. Detailed commit messages are a good way to record the
'why' points. Unlike in-code comments, they don't bloat and dilute the source.
Of course, they're also less immediate. (I guess I'm not sold on comment-
folding as an answer to this.)

It's also a point in favour of fine-grain commits. If you squash your commits,
'git blame' becomes less able to help you track a line of code back to its
original motivations.

~~~
superhuzza
Personally I would consider listing assumptions as a 'why' comment.

Knowing the assumptions gives the reader the context for why certain decisions
were made, and why they may still be valid decisions or not.

~~~
MaxBarraclough
Come to think of it, 'assumptions' is awfully broad. I was thinking of in-code
assumptions ( _We assume x is non-negative_ ), but I think you're thinking of
requirements-level assumptions?

I agree that requirements-level assumptions ( _We assume the Vogon server will
allow us to make at most 4 connections at any time_ ) are exactly the sort of
thing that should be captured in comments. I'm not sure there's a bright line
between _assumptions_ and _requirements_ here, really.

My other point there was that any non-trivial code-level assumption that can
reasonably be captured with an assert, _should_ be captured with an assert, in
preference over a comment.

~~~
mason55
If you’re assuming x is non-negative I would want to know why. Is it a
function of what x represents in the real world? Is it something that we
agreed on but there’s no physical reason x can’t be negative? Did the dev just
assume x can’t be negative because it was easy and no one ever talked about
it? And if the code looks like it assume x will never be negative but there
are no comments explaining why then I’ll assume it just wasn’t thought
about/discussed at all and know to be careful around this code.

That way when I go to update this code in the future I know if and why I have
to worry about if x could be negative now.

