Syntax highlighter is wrong (2014) | Hacker News Reader

Syntax highlighter is wrong (2014)

jameshfisher.com

43 pointskqr41 comments

I disagree with every single point.

I don’t need help with reading comments. I need help with reading code. Highlighting comments distracts me from what I need to focus on to read. The idea that comments are bad, is also one I disagree with.

WRT to git diff, I intuitively understood green is added. No one had to tell me. The two “better” diff examples would cause me to misunderstand or not understand intent.

This +1000. By graying out comments the editor/site makes it much easier to separate these two separate-yet-interleaved streams of information. I don't want a big ugly call-to-action on every single comment.

This guy seems like he should just customize his own syntax highlighting and diffing tools and be done with it.

I highlight comments bright red in all editors, and it's really no different in terms of "filtering into separate streams". What it does significantly change is my initial approach to entering foreign code. Instead of immediately reading the code, my eye is drawn to the comments, often providing me with insightful commentary that then guides me in understanding the code. As a bonus, it has also made me more sensitive to outdated comments, which I views as a plus.

Of course, comments also often contain the hidden assumptions or limitations of the algorithm that were too expensive to check. Often the comments actually do contain the bug you're looking for.

I suggest you give it a shot. I didn't expect it to make as much of a difference as it ended up doing.

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

Couldn't be more wrong on this one.

I don't doubt you, because that's a broad generalization, but do you know of contrary examples?

Japan

It's the entire sinosphere that associates red with positive traits and green negative.

Not Japan. China.

The Japanese stock exchange shows positive values in red, and negative in green. The connotations of red are not limited solely to China.

You mean "Not just Japan. China."

https://blog.emojipedia.org/why-does-the-chart-increasing-em...

Huh, interesting! Thanks.

Yes, the movie Doctor Strange in the Multiverse of Madness debunked that one. :-)

I don't think I generally agree with "Clean Code," but I do agree with the first value judgment in this post: that comments are important, possibly more important than the code, and that we're probably discouraging developers from writing comments by making them less visually appealing.

The very first "real" development environment I ever used[1] was absolutely miserable, except for two things: the comments were bright neon green, and the spellchecker was enabled (at least in my computer lab). I haven't written Java in over a decade, but I still configure each of my editors with that same bright green color for comments and with spellchecking, and I think both have made me a more diligent programmer.

[1]: https://en.wikipedia.org/wiki/DrJava

I actually like that comments are usually toned down. They don't cause runtime exceptions and compiler errors, they don't disturb the program flow, they are not the cause of the bug I'm trying to fix. Just some hints to help me understand the code. For really important comments you can still use `TODO`, `FIXME`, etc. which most editors highlight more.

Maybe we editors should include a REALLYIMPORTANT flag too. But the fact that I never thought about it before reading that article suggests it's not really important.

Agreed. Maybe I've had this wrong most of my programming career, but comments are usually for explaining the "why" of code if the code isn't that obvious by itself (and if this is the case, I usually try to refactor it first). It's rare that my comments ought to take precedence over the code itself.

If I do have something REALLYIMPORTANT (which is exceptionally rare), I plaster it all over so that it's practically not missable (esp. in code review). Sure, highlighting _that_ comment might help a bit during development, but I really don't think that use case is worth highlighting _all_ code in that case. But it could be a 'nice-to-have' for syntax highlighters.

How about a one line comment that summarizes what the block of code directly below does, in order to avoid the need to run an interpreter in your head while skimming code to find what you are interested in.

That little bit of extra information, which only takes a few seconds to type, can save a lot of people a lot of time afterwards.

I do this, and add any addition "why" or other needed detail indented under the first summary commented line.

You mean when the code is too long, and you summarize regions of it for easy location?

Making the comment large is good enough for that. But a really different tag may help here.

The example from Martin's book looks odd to me.

The comment is AFTER the code that it is commenting on. I can't remember seeing this before. Only before or at most at the end of the line.

Is that custom in any programming language community?

The diff example is clearer with red and green.

Not so clear with the new colors.

Maybe the author shouldn't think in bad and good but red = negative = minus and green = positive = plus.

I wonder in which color scheme he grasps the information faster.

I wouldn't be as opinionated as OP. While I do agree that javadoc style comments are a curse we should get rid of, I find comments inline with code to be better a bit tuned down. Usually, the comment is useful when you don't grasp why a particular line is there. You notice there is a comment, so you read it. It's better to get an overview of the code, then drill down to its details with the help of comments. But those did not get in the way for the initial readout to get the big picture.

IMHO it's the same reason editors offer folding functionality for code blocks. You get a big picture, then drill down to it, eliminating some clutter. For example, take Go's infamous `if err != nil { return err }`. I don't need to know every single one of them in a piece of code to get the big picture, so them being folded is good. Then upon further examination, I can expand them to see whether any special error handling is done at some place and why.

For diffing colors, that's why I prefer a good side-by-side viewer with syntax highlighting. The default unified diff output is pretty useless when more than 2 consecutive lines changed. That is something that GitLab and others get right: side by side, changes to a line highlighted to tell "hey, only this word in the line changed, but it still count as the whole line being replaced".

> While I do agree that javadoc style comments are a curse we should get rid of

Meh, I think javadoc is somewhat antiquated but otherwise an ok markup language for documentation. I do like that newer languages seem to have switched to a version of markdown for documentation.

Similar post: https://www.benkuhn.net/syntax/

The opening is already completely missing the point. In Bob's book, the comment is highlighted because the paragraph is talking about the comment. Drawing a red circle around something you want to point out doesn't mean that that thing always needs a red circle around it.

Your editor should be able to highlight comments (and adds/removes/line changes) however you want it to. Arguing about these defaults is more trivial than arguing about tabs vs spaces, or line endings.

Please don’t argue about either of those in reply to this comment. Both objectively have more of an impact on committed code, and that’s my only point. My functions are orange and my variables are blue. I don’t care how yours are distinguished, if they are, unless I’m reading your shared screen. It has less of an impact on my comprehension than minuscule font sizes.

I'm not sure if red and green necessarily have a negative and positive connotation to me. First, red and green are often colors for + and - and second, you can read the code you need and see why it was deleted.

It's funny, because those colors were clearly picked exactly because they have their positive and negative connotations, used as a metaphor for literally positive and negative changes.

That's the same reason people use them on numbers too.

But deleting code (a red diff) is the most positive code change anyone can make

Think of it more as state instead of transition: The code in red was bad so it had to be replaced with the good green code.

the cultural association makes it easier to parse- a red diff is clearly very good because lots of bad code (red) is being removed (red)

if your boss looks at a red diff and thinks it's bad, that's a you and him problem, while the primary purpose for color syntax continues to be making it easier to parse for people who know what they're looking at

It's literally negative. You are removing things.

It may add value, so may be figuratively a very positive change. But not literally.

I would agree, the connotations come from internal classifications from the reader, and the classifications just don't bear scrutiny in most cases.

A red apple is not inherently bad nor is a green apple inherently good. A person might enjoy one versus the other to eat, but if you just ask someone to identify attributes of an apple, the color likely won't prompt statements about the good/bad nature of the apple, and instead would decide the apple's use based on your needs. This can be done with just about any color association and at its core, people will include the context when considering the associations. Red machines are better because they're faster, after all, even if you're not making a WH40k joke.

I think the author of the article overstates the implicitness of the associations they make with red/green and propose that everyone has such strong associations. When I read a diff, the color doesn't matter, I just need to know what it indicates. I set my terminal colors and syntax highlight colors not to indicate some specific judgement on the colors, but because I want different things to stand out so when I am scanning.

Bright red stands out well in general, so it's useful for errors so I catch it when scrolling, which typically are what I'm interested in if I'm checking a log. Based on my primary interest, I pick the other colors that are complimentary to red or opposing to help quickly categorize. With diffs, I am interested in what got the axe typically, because first I want to see "what did we have before?"; it's very difficult to judge if what was added is an improvement without knowing the context of what was replaced, so for me, it makes sense to focus on what was originally there, then see what was changed. This is naturally _my_ association and interpretation, and frankly it could work with any scheme assuming the colors were different enough.

The difficult part with comments is they are the only thing in the codebase that's not checked by the complier. Comments are something that should be used sparingly as the OP. They occasionally are useful but good code should be self commenting by choosing good names and structuring algorithms in a reasonable way.

I think at the end of the day it's insane to expect the people that who were unable to express themselves clear in formal code will somehow gain the ability to express themselves clearly in informal comments.

My syntax highlighting scheme is very minimal. White on black, with only string literals slightly grey, and comments slightly greyer. To me that provides enough of a distinction that I can distinguish the three types of content. The rest is a distraction to me.

Although now that I think about it I could make number literals coloured the same as the string literals, but I don’t really have any trouble distinguishing numbers from code (whereas sometimes strings can look like code).

I always liked the argument that what should be highlighted is not the syntax but the structure, that is to say, different variables and objects should get different colors, this is never done because it requires your editor to understand the state of your program, that is, a very hard task.

Other that that, at least for me, a little syntax highlighting goes a long way, mostly I don't use it at all.

It’s actually a somewhat solved task, by editors that support LSP.

I can’t think of a UX that would work well for generally colouring identifiers distinctly though.

One nice feature that does exist is selecting an identifier and highlighting other instances of that identifier (semantically, not just by string matching). This makes actively reading code a lot easier. It would be interesting to see this extended to allow multiple selections.

Are there any editors which lay out comments on the side of the code? Or perhaps one that toggles their visibility?

> Are there any editors which lay out comments on the side of the code?

I've seen that done for read-only code readers, Backbone.js' annotated source code [1] comes to mind, but I wonder how that would work for the editing portion of an editor.

[1] https://backbonejs.org/docs/backbone.html

> Or perhaps one that toggles their visibility?

Vim has code folding ability, which you can set up to apply to comments. I'm sure this isn't exclusive to Vim though.

I don't know, seeing huge red chunks in diff view might be the most delightful thing for most programmer, red definitely doesn't indicate wrong for most people in this context.

When syntax highlighter is wrong, I do the // "

Reply on news.ycombinator.com