14 ms·

Syntax highlighters are wrong (2014)

233 points by TuringTest 7y ago

alkonaut 7y ago
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.
- chungy 7y ago
  Emacs is among them.
- djsumdog 7y ago
  Most of the JetBrains editors highly TODO in a bright color.
kieckerjan 7y ago
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.
- saagarjha 7y ago
  I like basic syntax highlighting, but I'm not picky about the coloring other than it being Solarized in the cases where I can choose. I like that different things are highlighted differently: it's a simple semantic bug checker ("Why is everything red? Oh, I forgot to close that quote.").
- chriswarbo 7y ago
  The quote issue is quite true, although some editors have "smart" input modes which will introduce open+close syntax at the same time, and "step over" the close syntax when typed (rather than duplicating it). For example in Emacs https://www.emacswiki.org/emacs/AutoPairs https://www.emacswiki.org/emacs/AutoPairs
- spatulon 7y ago
  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 7y ago
    Is that 0x1_0000 a typo? Shouldn't it be 0x1_000 or 0x10_000 instead?
    - 1_player 7y ago
      It makes sense to group hexadecimal numbers by two (nibbles). In this case 0x1_0000 is the least-significant bit of the third byte. If that's a bit flag encoded in a 32bit value, I also like 0x0001_0000 for clarity.
    - spatulon 7y ago
      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_terminal/src/renderer/mod.rs#L499 https://github.com/jwilm/alacritty/blob/master/alacritty_ter... I agree 0x1_000 or 0x10_000 would make more sense, but it doesn't look like the actual value used is hugely significant.
taneq 7y ago
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 7y ago
  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.
saagarjha 7y ago
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…).
ktpsns 7y ago
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 7y ago
  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 7y ago
    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")
Kovah 7y ago
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.
hu3 7y ago
Previous discussion (2014): https://news.ycombinator.com/item?id=7728781 https://news.ycombinator.com/item?id=7728781
martin_a 7y ago
> 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.
- divanvisagie 7y ago
  Agreed. If I'm looking for comments, the washed out look is easy to pick up. Also. many people don't or can't follow clean code. Could you imagine the mess if you were writing an API that required JSdoc with the author's proposed highlighting scheme? Or Golang's enforcement of comments on public functions?
- azernik 7y ago
  Agreed about the red. I find it deeply satisfying.
- onion2k 7y ago
  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.
  - 7y ago
sacado2 7y ago
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.
- taneq 7y ago
  > 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. This is where multiple rulesets could come in handy. Your editor which you're using for debugging should keep the commented-out code nice and subtle, but when you go to commit it should be bright purple with yellow spots.
  - jakear 7y ago
    You could actually do exactly that in VSCode. I might have to try making it.
- flohofwoe 7y ago
  Why "require" documentation comment blocks to be parsed by external tools and read elsewhere? It's perfectly fine to have big blocks of documentation comments right in the code, and to be consumed there. The current "fashion" of making comments as unreadable as possible in most syntax highlighter themes is indeed my main gripe with them. Comments don't have to particularly stick out, but it would at least help to make them as readable as the actual source code.
  - rightbyte 7y ago
    Ye. Reading eg. Javadoc verbatim is awefull. There are nice doc generators that allow natural language with markup only for special attributes.
scandox 7y ago
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 7y ago
  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.
  - colatkinson 7y ago
    Yeah I definitely agree with this. If I'm incrementing x in such a way that it's pretty clear what the meaning is (e.g. it's actually called like cur_page or something and I'm iterating over paginated data), then comments don't add a lot of value. Especially if they're not actually kept up to date with code changes. On the other hand, comments like, "Hey don't change this because if you do, it'll break things in subtle and hard to test way because x," are definitely useful.
  - lozenge 7y ago
    but pageCountDisplayed = pageCount + 1 is more useful still.
    - hnlmorg 7y ago
      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).
codethief 7y ago
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
galfarragem 7y ago
Tonsky (Nikita Prokopov) view on syntax highlighting: https://www.youtube.com/watch?v=l1b7Da2DnPo&feature=youtu.be&t=833 https://www.youtube.com/watch?v=l1b7Da2DnPo&feature=youtu.be...
eterm 7y ago
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.
DarkWiiPlayer 7y ago
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.
- underwater 7y ago
  Comments can convey hard-won information. Often developers will spend hours digging into an issue and then see a configuration or subtle change as the end result. That inocuous little bit of code is some of the most expensive, and brittle, code in the code base, but there is nothing to suggest it. They might attempt to capture that knowledge in a git message, but that is destined to be burried in the sands of time.
  - gmac 7y ago
    Absolutely this. The time I find comments really valuable is when they remind me (or someone else) 18 months down the line that the other, obvious way to do this thing is subtly wrong, or when they justify using this particular value (perhaps with a link to some outside reference). Comments are mostly hints and metadata. For example, in a recent file that deals with the database: // note: the ROW() constructor below is required in Postgres 10+ if we're updating a single column (There was a syntax change from Postgres 9 that was caught by our tests) // these are the only meaningful values in Postgres: // see https://www.postgresql.org/docs/11/sql-set-transaction.html (Justifying why we don't support the whole SQL-standard range of transaction isolation types) // on trapping the following two rollback error codes, see: // https://www.postgresql.org/message-id/1368066680.60649.YahooMailNeo@web162902.mail.bf1.yahoo.com // this is also a good read: // https://www.enterprisedb.com/blog/serializable-postgresql-11-and-beyond (An audit trail for why we catch some error codes but not others that initially look similar)
signal11 7y ago
> 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 7y ago
  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 7y ago
    I'd also object to "stop", as in at a traffic like, connoting "bad". A break from driving is often welcome!
  - fourier_mode 7y ago
    > Even in the US red isn't "bad" *always "bad". Some bad examples, red is associated with the evil political party i.e. Republicans.
sradman 7y ago
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 7y ago
  Thanks for pointing out that NB doesn't denote minor comments (as I believed), quite the opposite.
jrockway 7y ago
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.)
Sharlin 7y ago
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 7y ago
  Blue yellow is also a form right? What is a safe color blind-friendly pair of contrasting colors?
  - edejong 7y ago
    The interwebs is full of examples (search for categorical color palette colour blind). But colorbrewer [1] is well known. And this [2] article "Color Universal Design (CUD) - How to make figures and presentations that are friendly to Colorblind people" gives loads more information. [1] http://colorbrewer2.org/#type=qualitative&scheme=Paired&n=3 http://colorbrewer2.org/#type=qualitative&scheme=Paired&n=3 [2] http://jfly.uni-koeln.de/color/ http://jfly.uni-koeln.de/color/
  - pluma 7y ago
    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 7y ago
      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.
mcv 7y ago
> "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?
gcoda 7y ago
There is awesome plugin for VSCode, Better Comments. I disabled most of highlighting in syntax, rainbow brackets and better comments is more than enough
Quipunotch104 7y ago
This article is from 2015.
- oinkgrr 7y ago
  2014 even.
- ac42 7y ago
  It's a comment, it may be obsolete.
pluma 7y ago
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.
j0057 7y ago
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!
franciscop 7y ago
> 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.
- IshKebab 7y ago
  It's true in the places where they decided to use green for adding lines and red for removing them. That said I don't think it matters. The benefit of not making removing lines look like a bad thing is definitely outweighed by the cost of not making it obvious which colour means which. Was olive for lines added? I can never remember...
- EForEndeavour 7y ago
  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.
  - AlexTWithBeard 7y ago
necovek 7y ago
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.
buro9 7y ago
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 7y ago
  >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.
Elte 7y ago
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 7y ago
  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.
m3at 7y ago
Note that vimdiff does use neutral colours by default.
adamlett 7y ago
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
davedx 7y ago
> 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.
polotics 7y ago
Totally agree with the article. Just note: red/green is not that global a value-signal, the Chinese got it backwards.
tobr 7y ago
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.
V-2 7y ago
> 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?
phodge 7y ago
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.
rsl7 7y ago
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.
codr7 7y ago
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.
- kqr 7y ago
  I strongly recommend trying a middle ground. I find nearly all highlighting schemes in use today overly garish, so I always find myself customising my own with relatively few colours with the idea of doing as little as possible to bring out the structure of the code: - Comments and string literals can look like code without being code, so they get their own separate colours to make it easier to quickly scan past to where they end. - Types live in a different dimension from the rest of the code, and tell me a lot about what it does, so they get a different colour. And, finally, the one I've been trying for a while but am still not convinced about: - Structural keywords (for loops, branches, etc.) get a separate colour as well. All these colours are of course relatively neutral. I'm especially confused by people who use bright red for anything. That's a colour I use extremely sparsely for actual errors and bugs.
- w56rjrtyu6ru 7y ago
  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.
ajross 7y ago
> 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 7y ago
  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 7y ago
    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.
deleted 7y ago
[deleted]
nnq 7y ago
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 7y ago
  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.
awinter-py 7y ago
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.
bastawhiz 7y ago
> 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.
Snortibartfast 7y ago
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?
bschwindHN 7y ago
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.
fourier_mode 7y ago
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)
Shorel 7y ago
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.
kazinator 7y ago
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.)
yb71 7y ago
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.

233 points by TuringTest 7y ago

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.

chungy 7y ago
Emacs is among them.
djsumdog 7y ago
Most of the JetBrains editors highly TODO in a bright color.

kieckerjan 7y ago

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.

saagarjha 7y ago
I like basic syntax highlighting, but I'm not picky about the coloring other than it being Solarized in the cases where I can choose. I like that different things are highlighted differently: it's a simple semantic bug checker ("Why is everything red? Oh, I forgot to close that quote.").
chriswarbo 7y ago
The quote issue is quite true, although some editors have "smart" input modes which will introduce open+close syntax at the same time, and "step over" the close syntax when typed (rather than duplicating it). For example in Emacs https://www.emacswiki.org/emacs/AutoPairs https://www.emacswiki.org/emacs/AutoPairs
spatulon 7y ago
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 7y ago
  Is that 0x1_0000 a typo? Shouldn't it be 0x1_000 or 0x10_000 instead?
  - 1_player 7y ago
    It makes sense to group hexadecimal numbers by two (nibbles). In this case 0x1_0000 is the least-significant bit of the third byte. If that's a bit flag encoded in a 32bit value, I also like 0x0001_0000 for clarity.
  - spatulon 7y ago
    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_terminal/src/renderer/mod.rs#L499 https://github.com/jwilm/alacritty/blob/master/alacritty_ter... I agree 0x1_000 or 0x10_000 would make more sense, but it doesn't look like the actual value used is hugely significant.

taneq 7y ago

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

saagarjha 7y ago

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

ktpsns 7y ago

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 7y ago
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 7y ago
  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")

Kovah 7y ago

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.

hu3 7y ago

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

martin_a 7y ago

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

divanvisagie 7y ago
Agreed. If I'm looking for comments, the washed out look is easy to pick up. Also. many people don't or can't follow clean code. Could you imagine the mess if you were writing an API that required JSdoc with the author's proposed highlighting scheme? Or Golang's enforcement of comments on public functions?
azernik 7y ago
Agreed about the red. I find it deeply satisfying.
onion2k 7y ago
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.
- 7y ago

sacado2 7y ago

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.

taneq 7y ago
> 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. This is where multiple rulesets could come in handy. Your editor which you're using for debugging should keep the commented-out code nice and subtle, but when you go to commit it should be bright purple with yellow spots.
- jakear 7y ago
  You could actually do exactly that in VSCode. I might have to try making it.
flohofwoe 7y ago
Why "require" documentation comment blocks to be parsed by external tools and read elsewhere? It's perfectly fine to have big blocks of documentation comments right in the code, and to be consumed there. The current "fashion" of making comments as unreadable as possible in most syntax highlighter themes is indeed my main gripe with them. Comments don't have to particularly stick out, but it would at least help to make them as readable as the actual source code.
- rightbyte 7y ago
  Ye. Reading eg. Javadoc verbatim is awefull. There are nice doc generators that allow natural language with markup only for special attributes.

scandox 7y ago

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 7y ago
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.
- colatkinson 7y ago
  Yeah I definitely agree with this. If I'm incrementing x in such a way that it's pretty clear what the meaning is (e.g. it's actually called like cur_page or something and I'm iterating over paginated data), then comments don't add a lot of value. Especially if they're not actually kept up to date with code changes. On the other hand, comments like, "Hey don't change this because if you do, it'll break things in subtle and hard to test way because x," are definitely useful.
- lozenge 7y ago
  but pageCountDisplayed = pageCount + 1 is more useful still.
  - hnlmorg 7y ago
    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).

codethief 7y ago

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

galfarragem 7y ago

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

eterm 7y ago

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.

DarkWiiPlayer 7y ago

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.

underwater 7y ago
Comments can convey hard-won information. Often developers will spend hours digging into an issue and then see a configuration or subtle change as the end result. That inocuous little bit of code is some of the most expensive, and brittle, code in the code base, but there is nothing to suggest it. They might attempt to capture that knowledge in a git message, but that is destined to be burried in the sands of time.
- gmac 7y ago
  Absolutely this. The time I find comments really valuable is when they remind me (or someone else) 18 months down the line that the other, obvious way to do this thing is subtly wrong, or when they justify using this particular value (perhaps with a link to some outside reference). Comments are mostly hints and metadata. For example, in a recent file that deals with the database: // note: the ROW() constructor below is required in Postgres 10+ if we're updating a single column (There was a syntax change from Postgres 9 that was caught by our tests) // these are the only meaningful values in Postgres: // see https://www.postgresql.org/docs/11/sql-set-transaction.html (Justifying why we don't support the whole SQL-standard range of transaction isolation types) // on trapping the following two rollback error codes, see: // https://www.postgresql.org/message-id/1368066680.60649.YahooMailNeo@web162902.mail.bf1.yahoo.com // this is also a good read: // https://www.enterprisedb.com/blog/serializable-postgresql-11-and-beyond (An audit trail for why we catch some error codes but not others that initially look similar)

signal11 7y ago

> 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 7y ago
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 7y ago
  I'd also object to "stop", as in at a traffic like, connoting "bad". A break from driving is often welcome!
- fourier_mode 7y ago
  > Even in the US red isn't "bad" *always "bad". Some bad examples, red is associated with the evil political party i.e. Republicans.

sradman 7y ago

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 7y ago
Thanks for pointing out that NB doesn't denote minor comments (as I believed), quite the opposite.

jrockway 7y ago

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

Sharlin 7y ago

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 7y ago
Blue yellow is also a form right? What is a safe color blind-friendly pair of contrasting colors?
- edejong 7y ago
  The interwebs is full of examples (search for categorical color palette colour blind). But colorbrewer [1] is well known. And this [2] article "Color Universal Design (CUD) - How to make figures and presentations that are friendly to Colorblind people" gives loads more information. [1] http://colorbrewer2.org/#type=qualitative&scheme=Paired&n=3 http://colorbrewer2.org/#type=qualitative&scheme=Paired&n=3 [2] http://jfly.uni-koeln.de/color/ http://jfly.uni-koeln.de/color/
- pluma 7y ago
  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 7y ago
    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.

mcv 7y ago

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

gcoda 7y ago

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

Quipunotch104 7y ago

This article is from 2015.

oinkgrr 7y ago
2014 even.
ac42 7y ago
It's a comment, it may be obsolete.

pluma 7y ago

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.

j0057 7y ago

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!

franciscop 7y ago

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

IshKebab 7y ago
It's true in the places where they decided to use green for adding lines and red for removing them. That said I don't think it matters. The benefit of not making removing lines look like a bad thing is definitely outweighed by the cost of not making it obvious which colour means which. Was olive for lines added? I can never remember...
EForEndeavour 7y ago
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.
- AlexTWithBeard 7y ago

necovek 7y ago

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.

buro9 7y ago

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

Elte 7y ago

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

m3at 7y ago

Note that vimdiff does use neutral colours by default.

adamlett 7y ago

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

davedx 7y ago

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

polotics 7y ago

Totally agree with the article. Just note: red/green is not that global a value-signal, the Chinese got it backwards.

tobr 7y ago

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.

V-2 7y ago

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

phodge 7y ago

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.

rsl7 7y ago

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.

codr7 7y ago

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.

kqr 7y ago
I strongly recommend trying a middle ground. I find nearly all highlighting schemes in use today overly garish, so I always find myself customising my own with relatively few colours with the idea of doing as little as possible to bring out the structure of the code: - Comments and string literals can look like code without being code, so they get their own separate colours to make it easier to quickly scan past to where they end. - Types live in a different dimension from the rest of the code, and tell me a lot about what it does, so they get a different colour. And, finally, the one I've been trying for a while but am still not convinced about: - Structural keywords (for loops, branches, etc.) get a separate colour as well. All these colours are of course relatively neutral. I'm especially confused by people who use bright red for anything. That's a colour I use extremely sparsely for actual errors and bugs.
w56rjrtyu6ru 7y ago
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.

ajross 7y ago

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

deleted 7y ago

[deleted]

nnq 7y ago

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

awinter-py 7y ago

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.

bastawhiz 7y ago

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

Snortibartfast 7y ago

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?

bschwindHN 7y ago

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.

fourier_mode 7y ago

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)

Shorel 7y ago

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.

kazinator 7y ago

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

yb71 7y ago

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.