Syntax highlighters are wrong

by jamesfisher • 12 years ago

139 124 12 years ago

masterleep• 12 years ago

Almost everyone intuitively knows that red = deletion and green = insertion. Nobody knows what yellow and blue refers to. So how is that more usable?

freshhawk3• 12 years ago

I'm pretty sure I learned that convention. Why would it be intuitive? What's the association between red/remove and green/add?

robinh• 12 years ago

The color red is often associated with bad; needs to stop; wrong. Removal isn't such a big step from there, I think. The opposite probably applies to green.

daveid• 12 years ago

I think that pretty much everywhere green==positive and red==negative.

jowiar• 12 years ago

I don't buy that. Most programmers have learned that, in a diff, red = deletion and green = insertion. But I'm not sure that is "intuitive" as much as "learned behavior".

rhizome2• 12 years ago

Red means "stop," green means "go," is also learned behavior.

cheradenine01• 12 years ago

In accounts, we often hilight negative numbers in red. It's one of the defaults in things like excel.

So red text has come to mean '-'.

'-' is also 'taken away', so I can see why it's logical to have it in red.

As for green.. well - opposite.

nkrumm• 12 years ago

In the field of genetics-- and specifically for copy number variation (i.e., big chunks of genome deleted or inserted)-- the red/green contrast was deemed inaccessible to color-blind individuals, and so a new red/blue scheme was implemented as a consensus scheme.

red - deletion of genetic sequence blue - insertion of genetic sequence

1: https://www.iscaconsortium.org/index.php/the-news/95-the-mea...

matthewmacleod• 12 years ago

As per the siblings, I don't really agree that this is intuitive. What it definitely is: widespread, accepted, well-known, not confusing - pretty much the same thing.

RobotCaleb• 12 years ago

For myself, and many others, green is green and red is also green. That likely presents a problem.

dionidium• 12 years ago

I believe the reason for this strange color scheme is the lack of a revision control system. Back in the dark ages of programming, we didn’t use them. We edited files on disk, and that was that. In that environment, a deletion is dangerous. If you decide you want it again after you delete it, well, that’s tough.

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

Velox• 12 years ago

One of the main rants in this is about superfluous comments. I completely agree that comments which are superfluous should be removed. However all his examples are JavaDoc. Yes, in the code they are useless because of the variable declarations, however they are of great use in an IDE.

hadem• 12 years ago

I was thinking the same thing. Yes, the comments might look pointless when viewing source code on GitHub but really makes life easier with an IDE and documentation generation.

Sure, take out those comments, but then his next blog post would be about the lack of decent documentation available for various projects...

peeters2• 12 years ago

And most syntax highlighters actually allow different styling on Javadoc comments than on block comments or line comments. There's no reason to treat them the same.

pcmonk• 12 years ago

I disagree about insertions and deletions. The primary purpose of colors should be to communicate more information without us having to think about. Having standard color schemes is really helpful. If every service uses different insertion/deletion colors, that's just more headache for us.

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

TheCrownedFox2• 12 years ago

I think the bigger problem with using red and green for commit changes is for the folks that are red/green colorblind.

tormeh2• 12 years ago

I don't think this should be in the application. It's a monitor or OS issue. Couldn't we just use a color calibration matrix to map all colors to the spectrum the colorblind person does see?

rmc3• 12 years ago

Which is weird when you think about it. red/green colourblindness is way more common in men and tech is quite male dominated.

micro-ram• 12 years ago

Red/Green colorblind doesn't mean we don't see red and green, it's just not as powerful. It should read Red/Green deficient. Maybe that is why it doesn't seem so bad because to a Red/Green colorblind person the colors are more subdued.

joesb• 12 years ago

It still work if you use different brightness for each color. Being colorblind doesn't mean you see red as white.

davidgerard• 12 years ago

This is precisely why Wikipedia switched diffs from red/green to orange/blue.

rorygreen• 12 years ago

These were also my thoughts when reading the article. I have always associated red with old and green with new. I also do not think red conveys the negative meaning the author suggests it does.

I do, however, believe the author has a very strong argument relating to code comments. I'd like to see a shift towards this style of highlighting in the future as I often find myself having to modify nearly every colour scheme I use to make comments far more prominent.

mc_hammer• 12 years ago

I think this may be correct. Personally I always wanted the syntax highlighter to highlight only function calls and object method calls.. ex: .Trim() would get highlighted in mystr.Trim()

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

matthuggins• 12 years ago

The comment talk I can get behind. However, the change from red/green to blue/yellow for file change is non-intuitive, and I hope to never see it.

pubby• 12 years ago

Aw, I was hoping article was going to be about the highlighter's grammar rather than its colors. Perhaps there exists a system other than, "colorize keywords and comments". Or maybe build color into the language itself, as done by colorForth.

artursapek• 12 years ago

I think the author is overthinking it in the second section: we're not discouraging deleting code by marking it red. We're simply denoting that it was removed, or killed off (he drew the connection of red to blood, and green to new life).

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

gcb0• 12 years ago

Yep. And it's mostly about communicating. That they choose red for removals and green for insertions is meaningless. We may argue the same nonsense about stop lights. A parked car is safe a moving one can kill. So let's replace the stop lights colors. What? Yeah. Silly argument. The colors do not matter at all. Sometimes a cigar is just a cigar.

When programmers all around the world look at the red/green in a diff they understand it, without having to search for a legend explaining the colors.

jgraham2• 12 years ago

This is something that most code review tools apart from GitHub get right. For example Critic, Review Board, Phabricator and Gerrit all implement side-by-side diffs with correct syntax highlighting on each side. I don't know why the GitHub experience is so far from the state of the art.

lilyball• 12 years ago

I would imagine it's easier to do syntax highlighting on side-by-side, because you can just reuse your existing syntax highlighter. But when presenting the `-/+` style of diff, you need a custom syntax highlighter that not only can skip over the `-/+` tokens but can also handle having two separate-but-intertwined non-contiguous highlighting states (because the `-` lines will be using a different state than the `+` lines).

And then what do you do if the state ends up different when you hit the context lines again? There's no obvious choice as to how to highlight those.

juliendorra• 12 years ago

about comments being washed out: in the quest of writing good source code for kids (easy for kids to read, adapt and use) I found that comments should be not only an integral part of the source, but probably not highlighted as a single block, with an uniform color. For kids and beginners, we should have a highlighter for comments that bold words between *, that put some emphasis on titles in comments, that makes function/variable names in comments jump out. Also, we could highlight inline comments (at the end of a line of code, generally frowned upon but potentially useful for beginners and kids) as yellow stickies.

sitkack2• 12 years ago

And tokens in the comments that match or nearly match tokens in the code should be colored the same or even have arrows drawn between them when hovered over.

rwbcxrz• 12 years ago

Most editors allow you to customize the syntax highlighting color scheme. It's a bit more difficult in a web editor, but is possible with some JavaScript and an extension like Greasemonkey. Then again, how often are you really using the GitHub code browser -- if it's a lot, wouldn't it be easy enough to clone the repo and explore it in the editor of your choice?

ma_mazmaz• 12 years ago

This is blatantly wrong: "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. "

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

robert_tweed• 12 years ago

I completely disagree that comments should be called out in bold because they are supposed to add important information. Even in code where that is the case, they are still just metadata. Comments are there to help you understand something. Comments should never be shouting at you, drowning out the code itself. We only have so much attention to spare, and most of that attention should be focused on the actual code, not the comments.

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

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

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

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

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

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

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

I write code that needs something like this maybe once every 6 months. Do I want every single comment that I write called out with equal importance? Nope. Is limiting comments to only comments of such dramatic urgency a good idea? Also no.

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

recursive• 12 years ago

I think less code usually means less complexity. But less lines doesn't really correlate to less code.

harsh1618• 12 years ago

I agree with most of the first section but there are scenarios where washed out comments are better. If I comment out a block of code while debugging, I don't want it to be bold and highlighted. Maybe highlighters should be able to differentiate between natural language and code.

Kiro• 12 years ago

I don't agree with a single thing in this article so please don't tell me what's wrong when there clearly are different views on this matter.

noonespecial2• 12 years ago

The code itself is the "truth". The comments are commentary.

  //Set x to be 4
  x=5;

Which would you rather have bold and jumping out at you when skimming? Comments can be wrong because tweaks happen.

falcolas2• 12 years ago

To me, this is a terrible example, because it's a useless comment. The comment should explain what "x" is for, not what you're doing to it. I you have a comment about what "x" is for, which becomes more important? The assignment, or the explanation?

peeters2• 12 years ago

If you have to explain what x is for with a comment, maybe x is a bad name in the first place?

noonespecial2• 12 years ago

Shrug. Most of the code I have to deal with regularly is primarily commented with profoundly unhelpful, often blatantly incorrect nuggets such as this. Forever what and never why. It seems better if it just faded into a fossilized archeology that only needed to be Gandalfed in the most dire circumstance.

In my situation, making the comments "stand out so that people will make better ones or fix them" seems optimistic to the point of being naive. We may in the end be down to the old "what should be" vs "what is".

jamesfisher• 12 years ago

I'd much rather have the `x=5` jump out at me, because the example comment is entirely redundant. However, if the example was

    // removing this will cause a segfault because ...
    x=5;

then I would rather have the comment jump out at me.

voyou• 12 years ago

"I would rather have the comment jump out at me."

Really? The only time you need to know that removing that line will cause a segfault is if you are going to remove that line; but, if you're going to remove the line, you're surely going to check the comment above it, even if the comment doesn't jump out at you. Even an important comment is still irrelevant except when you are looking for clarification about the code it comments on; so I don't think it ever makes sense for comments to be emphasized more than the code.

adnzzzzZ• 12 years ago

One of the points made by the article is that if syntax highlighters made comments jump out at people, they wouldn't be so eager to comment unnecessarily (like in your example) since it'd start looking bad. It's a solution that fixes two problems in one go.

wmt• 12 years ago

Having the comment bolded would be excellent! It would immediately highlight that the comment is both useless and incorrect, and should be removed. The only comments that should remain are those that you really don't want to miss.

dyadic• 12 years ago

I'm sold on the argument in the article, I'd rather have the comment jump out and be deleted than see it sink into the background and remain.

jayd16• 12 years ago

So I guess we're just going to have a completely barren Javadoc then?

walshemj2• 12 years ago

1st world problems - some people have obviously never had to debug on a 3 inch thick printout on fan fold paper where he only highlighting was the highlight pens you used.

walshemj2• 12 years ago

Oh dear some one got out of bed the wrong side today :-)

gooseyard2• 12 years ago

These "<blank> is wrong" or "you're doing <whatever> wrong" titles are tedious. Tell me about the better one you've written or STFU.

deluvas• 12 years ago

Yes, exactly! I am tired with these clickbait titles on HN. Come up a better title, damn it, this isn't DailyMail.

coldtea• 12 years ago

Rephrased: This "Your cake is poisonous" talk is tedious. Tell me about the healthier cake you've baked or STFU while I eat my cake.

What I mean is, criticizing something is useful in itself. It's not necessary to also propose a better way. Sometimes it's enough to STOP doing something, you don't have to find an alternative for it.

gooseyard2• 12 years ago

sometimes, but not this time.

jroseattle• 12 years ago

Because there is only one way for it to be "correct", eh?

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

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

owenversteeg• 12 years ago

Although I like the idea of comments in a stand-out color, red and green for deletion and insertion is absolutely necessary. It's intuitive and the standard, and using other colors (ugly tones of yellow and purple) is both ugly and confusing. If I showed the red/green screen to someone, they'd intuitively know what's being deleted and not. If I showed the purple/yellow screen to someone, they'd scratch their heads.

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

Patrick_Devine• 12 years ago

This will sound weird, but I actually turn off the syntax highlighter most of the time. I usually use a black background in my terminal, and often the syntax highlighter (or even directory colours in a shell) are set to dark blue, which I have a really hard time distinguishing.

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

buro9• 12 years ago

I think the source of the problem with comments is that we try to make them serve two purposes:

1) Give the code clarity

2) Be the source of documentation

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

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

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

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

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

JoshTriplett3• 12 years ago

The syntax highlighting I use strongly emphasizes comments, making them bold and bright; I'm not at all a fan of highlighting schemes that fade out comments, like github's.

And I definitely agree about redundant comments. One of my earliest CS classes made it a requirement to have a comment for every line of code; those homework assignments looked like abominations (above and beyond being written in C++). These days, I try to avoid writing code that's too clever for its own good, and on the rare occasions when I can't make code self-documenting, I comment it instead.

As for the insertion/deletion item, though: I read so many diffs that I have a strongly established association for red->deletion->yay. Doubly so for the diffstat: always great to see -bignum +smallnum.

Regarding the linked article about "semantic highlighting", I've seen numerous complaints equating existing syntax highlighters to highlighting all the verbs in English prose, and "why on Earth would you want to do that?". Code is not prose; highlighting the verbs makes perfect sense given that code is a set of instructions. A better analogy would be to a step-by-step instruction manual, and I've seen many instruction manuals that highlight the verbs in each step.

dclowd9901• 12 years ago

I believe that a redundant comment is just someone being lazy while writing a comment. Each piece of code we write is part of a bigger whole, and if all you can write in a comment is a spaced out version of the name of a variable, you're doing it wrong. Tell us when the value is set, or what happens when it's set or how it affects other parts of the code; things that aren't immediately obvious by its nomenclature.

JoshTriplett3• 12 years ago

I believe that a redundant comment is just someone being lazy while writing a comment.

Perhaps, but it's also often someone being lazy when writing the code. It takes more effort to write self-documenting code that's optimized for understanding and editing rather than for writing. And I'll take good self-documenting code over well-commented code any day.

chenglou• 12 years ago

Related to the linked article at bottom (coding in color: https://medium.com/p/3a6db2743a1e/): I've been using the Sublime Colorcoder plugin (https://github.com/vprimachenko/Sublime-Colorcoder) and beside some instabilities, it's been working well. It's really nice to see the flow of a variable (or more) through a function, without manually highlighting the occurrences.

jackbauer• 12 years ago

Interesting article. I definitely try to avoid comments and let the code do the talking, I hope more devs would. My eyes ALWAYS skim over comments, unless I can't make sense of some agency dev's code, then I have to look at the comments if they exist.

Although I detest comments, making them stand out more and consequently wanting (hopefully) to write better code, is a plus. There will be some cases for comments, and it should be few and far between, and only super necessary (read Clean Code for contextual examples).

ryangallen• 12 years ago

Colors are certainly a significant part of user experience, so although I agree that these issues exist, I disagree with the solutions.

Comments shouldn't be pink/red because they are not necessarily a bad thing. Just make them bold and opaque.

Changing to blue and yellow for diffs is equally as wrong as red/green but more confusing. Blue signifies safe information and yellow signifies warning. It would be better to use the same color for deletions and additions but make deletions darker to show they are stale/rotted and additions brighter to show freshness.

pyre• 12 years ago

The author seems to brush off criticisms of his/her diff color ideas:

  [Edit: quite a few people disagree, which isn’t
  surprising, coming from people that already read
  diffs all day. It would take some time to retrain
  your eye.]

Comments like "well these people are just stuck in their ways," don't really disprove criticisms of your ideas.

Also, the author also seems to choose the colorscheme for comments base on his/her ideas of how one should use comments. This is less an argument of how right/wrong current colorschemes are and more of a battle of "More Comments, Be Explicit" vs "Less Comments, The Code is Documentation".[1]

[1] I'll weigh in my anecdotes on the "code should be documentation" idea. I've been places where this was the mantra, and the code was a complex mess of spaghetti. The idea that all I had to do was "follow the code" is laughable when "following the code" could be a several hour affair just trying to determine what one option to a class did. Or usage of variable naming schemes from the 90's where everything was an abbreviation (presumably to keep variable names as close to 8 characters as possible) or avoiding name collisions by prepending characters ('ppc' already exists, so use 'qppc', but in other source files use 'rppc' or 'PPC').

timr6• 12 years ago

"Every comment here is redundant. The textual decoration attempts to assert its own importance, adding two non-semantic lines to every comment. And indeed the eye is drawn to the useless comments instead of the code. So, after looking at these useless comments all day, what do we do? We use our syntax highlighter to turn them off!"

Is it really such a burden to scan a few comments? Come on.

The real problem here is that most developers are total brats about reading code. They'd rather cut off their hand than read anything, and once you're in that mindset, anything that you can latch onto is the target for excessive, self-affirming hostility about the stupidity of the author: those comments are just useless! The idiot who wrote this code must be terrible! I now feel slightly more justified in re-writing everything!

Given that developers almost never write comments for anything, I'd rather see someone erring on the side of over-commenting. If I see code that has been commented in that way, and I see that the other methods are well-commented, I know that the developer was probably more careful than the person who wrote no comments at all. I'm more likely to trust the code. Moreover, having your editor insert a comment on every new method is really a best practice -- it gets you in the habit of documenting, because you always have that empty comment template, staring at you.

dfan• 12 years ago

The real problem in that case is that every function declaration turned into 1 line of declaration, 2 lines of comments, 1 line of whitespace, and 2 lines of "comment whitespace". Blowing up the amount of vertical space that code takes up by a factor of six really is a problem.

I think the main meta-issue with comments is that they live in the same space as the code at all. For a while I've thought that they might be better as marginal notes like other commentary often is, which is why I'm excited about ideas like Marginalia (http://gdeer81.github.io/marginalia/), though I haven't tried it myself.

timr6• 12 years ago

"Blowing up the amount of vertical space that code takes up by a factor of six really is a problem."

Is it? Maybe I'm the only person who has never experienced this problem. Especially with editor code folding, method nav, tags, etc., vertical space is almost never an issue for me. (Horizontal space, OTOH, is the bane of my existence...)

Marginalia is interesting, though...thanks for the pointer!

nitrogen• 12 years ago

There are a few solutions:

- Use a folding editor.

- Buy a bigger monitor.

- Use a split-pane editor with two+ views of one file (e.g. Vim).

- Write shorter functions.

Mithaldu3• 12 years ago

That is not the real problem, it's just an exacerbation of the underlying issue:

Comments must never describe WHAT the code does, but WHY it does so.

The code itself should clearly describe what it does. If you need comments for that, you've written unreadable code and need to write more readable code. Comments that describe the what just absolve the programmer from doing that, while putting more effort on everyone coming after them.

A comment that describes why a certain bit of code does something, describe something that the code itself cannot and thus help everyone.

krig5• 12 years ago

You couldn't possibly be more wrong. Comments that describe the code and not the intent are terrible for obvious and clear reasons: They are not checked by the compiler, and they are not checked at runtime. There are no assertions that flag when the comment has gone out of date. Comments that talk about what the implementation does are virtually guaranteed to be wrong. This is simple fact. The thing comments can do that code is less good at is express abstract intent, and they should be saved for that. However, more powerful and expressive languages can express much of that in code as well, and thus even such comments can often be removed.

Look. What is code, and what are comments? Code is stating some fact that is expressed in a well-defined grammar. It can be both 1) read by machines, and 2) read by humans. Code says something specific, and it has a specification or at least a reference implementation which describes the exact meaning of what the code says. Sure, it can be wrong, which simply means that it says something other than what the author intended, but what it says is well specified.

Comments, on the other hand, have no restrictions at all. They can be written in any language. They can be fragments of sentences or multiple paragraphs. If they do follow some structure, it is not enforced unless by some external tool, in which case the comment is, in fact, code as input to that tool, and the complexity of the program has increased by an order of magnitude as it is now written in multiple languages at once.

Comments are worse than useless and should always be seen as the last resort. Wherever there is a comment, there should be a language deficiency that prevented whatever needed to be said from being said in the language itself. If there is no such thing, and the comment merely states what the code already says in a well-defined manner, the comment is wrong and should be removed.

timr6• 12 years ago

It's fairly ironic that you've spent so many words re-iterating the argument that "code should be self-documenting".

You're right that comments don't maintain themselves, though. That's the job of a programmer, and if the programmer isn't doing their job, they probably shouldn't be working on a project with other people.

dgreensp2• 12 years ago

I take it you've never written code that someone else had to call into or maintain. You're basically arguing against documentation or explanation of any sort. Also, I assume you program in straight-up English -- all checked by the compiler -- or else some programming language of the future whose contours match the shape of thought and in which there is never any impedance mismatch between what you are trying to achieve and what you must instruct the computer to do.

And please don't say, "That's right, Haskell" or "Yes, my favorite LISP."

mamcx• 12 years ago

That is true if you read "comment" as "description". That is the weird connection in a lot of bad comment.

But in real life, what is truly a comment (https://en.wikipedia.org/wiki/Comment)? Is like in sports: A commenter talk about the game and add context to enrich the narrative of that game: "Mr. Jhon score a avg of NNN/MMM in this season"

A comment that is a description of what the code is doing, is redundant (if the language is not obscure). But as a "commentary" of the circumstances around that code, is useful:

"This code is a workaround of the BUG (url). TODO: Remove when it get solved".

bayonetz• 12 years ago

I agree that syntax highlighters are wrong...except when they are right!

There are times when you want the comments to recede into the background, such as when you are actively creating some new code and aren't reading your own comments. This is a great time to have comments greyed out. In fact, it is probably the most common case for a syntax highlighting IDE - to help you WRITE code.

Of course there are times when you want comments to stand out and scream at you, such as when revisiting your old code or trying to penetrate someone else's code. This is a great time have them highlighted in pink as the OP suggests.

You could imagine a hybrid, where inline comments are pink but greying out big multiline comments like those that precede methods and classes. Or a million other variations, depending on your context.

Of course, you can sort of do this already by customizing the colors in the IDE's settings area. But you only get to pick on context. Or maybe you can create a couple, but then you have to go back to settings and at least toggle between them.

Bottom line, I think this article could be better if it developed this idea that IDEs/Syntax Highlighters could be improved by giving users a good way to EASILY choose different code reading contexts/modes on the fly such as "authoring mode", "reviewing someone else's mode", etc.

lispm• 12 years ago

I wonder when literature will come standard with syntax highlighting.

restlessdesign• 12 years ago

I might take the author more seriously if he didn’t brush off every criticism in the most dismissive, holy-than-thou tone I’ve come across since I was in Williamsburg the other weekend.

robobro• 12 years ago

I missed where he suggests a better color scheme. He references it for pink commenting.

ebbv• 12 years ago

This article is way, way off base.

First of all, most syntax coloring de-emphasizes comments because they are not code. They are not necessary. They are potentially helpful hints which may or may not be needed. Ideally they aren't. So, they should not be attention grabbing.

The idea that making them attention grabbing and ugly is great because it encourages you to have as few of them as possible is ridiculous. It's trying to accomplish a reasonable task (minimal comments) by totally ass-backwards means (making the comments the most obvious thing on the screen.) It's like replacing the click of the turn signal noise in your car with a blaring klaxon to try to get old people to turn them off with more regularity.

Here's a tip for the author, who I can only assume is a novice programmer; if there's a universal practice which has been a certain way for several decades and you think it's wrong, re-examine your assumptions.

ttty• 12 years ago

I don't think that in github the additions are green because are good, but because +=green and -=red

mantrax52• 12 years ago

Looking for a problem where there is none, this author is...

The reason why comments are pale compared to code is because a comment always belongs to a given piece/block of code.

A comment doesn't exists for itself, it exists to clarify the next lines of code.

You scan code, and when the code doesn't say enough, you read the comment. So code is the primary thing, comments are important, but hierarchically they're subservient to code not the other way around.

Also, why on earth would doc comments be "redundant" and have to be removed? Why would green/red be bad for insertions/deletions? Give me break...

mantrax52• 12 years ago

Hey look, Uncle Bob said something about comments.

DELETE ALL COMMENTS AND CHANGE SYNTAX HIGHLIGHTING!

seth1010• 12 years ago

I disagree with the comment syntax highlighting. If I'm trying to fix a bug in some code, I'll read all the comments and then try to focus on what the code is actually doing. I don't need the comments trying to steal my focus away. Some times, I'll get vim to color comments the same as my background so they'll be invisible.

unfamiliar• 12 years ago

In practice, I usually choose a colour scheme based on how important the comments are. There exist plenty which either emphasise or de-emphasise the comments, just choose one that is appropriate for the way your project is commented. And I disagree that all of those comments you removed are useless. They make the code far more readable and remove any ambiguity about what is represented by the variables.

Why, then, are we psychologically rewarding additions with green, and punishing deletions with red?

I'm sorry, but this is absurd. And with regards to the replacement blue/yellow scheme:

Perhaps it’s not as pretty, but it’s more usable

It is far less usable. I glance at the red/green and know immediately which is which. I have no idea whether yellow or blue is deletion or insertion at first glance.

This post could have touched on much more, for example: should we really be highlighting keywords, shouldn't we just be emphasising flow control and identifiers? There are many interesting ideas to be explored in this area, such as highlighting rvalues/lvalues in C++, highlighting scope instead of keywords, etc.

Semaphor• 12 years ago

I use the default dark scheme for visual studio. Comments are in a well visible green [0].

So much for "virtually every highlighting scheme".

[0] http://imgur.com/Nfw7Lyd

gojomo• 12 years ago

Fainter doesn't necessarily mean "less important": it may just indicate a separate channel-of-interleaved-information, sometimes skippable. (And, since comments are less rigorous and less-definitive than the code, code readthroughs often want to toggle between considering them, and not considering them.)

Red doesn't necessarily mean danger or disfavor. Its use for removed-ranges owes mostly to longstanding use in editorial review (red pens), emphasis ([rubrication]), and as indication of stopping/ending (as in "discontinue this text") – without any inherent 'badness' evaluation.

vorg• 12 years ago

Why stop at highlighting? The syntax should be customizable also. Who needs to repeat the `protected` keyword, initial null value, or semicolons before the line ends? Perhaps instead of...

  protected HashMap children = new HashMap();
  protected int backgroundProcessorDelay = -1;
  protected LifecycleSupport lifecycle = new LifecycleSupport(this);
  protected ArrayList listeners = new ArrayList();
  protected Loader loader = null;
  protected Log logger = null;
  protected String logName = null;
  protected Manager manager = null;
  protected Cluster cluster = null;
  protected String humanReadableName = null;
  protected Container parent = null;
  protected ClassLoader parentClassLoader = null;

...we could write...

  protected(defaultInitialValue: null){
    HashMap children = new HashMap()
    int backgroundProcessorDelay = -1
    LifecycleSupport lifecycle = new LifecycleSupport(this)
    ArrayList listeners = new ArrayList()
    Loader loader
    Log logger
    String logName
    Manager manager
    Cluster cluster
    String humanReadableName
    Container parent
    ClassLoader parentClassLoader
  }

And that's just for starters!

Syntax highlighters are wrong

Related Stories