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.
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?
That's not the same. When you go from 3D to 2D you lose a dimension. Information is lost. When you map color spaces like I proposed you go from 1D to 1D, you're just compressing the data in that dimension. No information is lost (except because of the limits of numerical accuracy)
So you propose that colorblind people should make their OS turn all images, photographs and video into false color not correlating with reality because in some specific contexts color is used symbolically and it's important to distinguish between two colors? One option that might work would be a special drawing mode implemented in the OS graphics stack that did some mapping depending on what's configured in the accessibility settings; then applications could request that in the rare cases where it's important.
As a partially colorblind person (albeit easily capable of telling red from green here), while of course such a mode should not be required for programming, I wouldn't mind using it in general. The EnChroma glasses try to do this in real life, but they're expensive and only work in bright sunlight; if I can at least get the same for photos just by downloading something, it sounds interesting. (And probably already exists, so I should do some Googling.)
That's a really interesting idea. You'd want a fast toggle for it, so that you could use it primarily for browsing semantic content that uses colors, but not always for photographs or videos that represent the real world (unless those photos or videos contained such semantic content). It's not ideal, but much like assistive devices that translate vision to other nerve impulses (http://www.nei.nih.gov/news/briefs/weihenmayer.asp), it could be useful as a learned adaptation.
That said, it would also make sense for diff software in particular (as one of the most prominent software uses of red and green right next to each other for semantic purposes) to have an easily adjusted option for a different color scheme for the very common case of red/green colorblindness.
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.
I do realize this. I also know someone that has had problems with it on github's diffs. I do think it would be better to use other colors to avoid the issue entirely.
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.
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.
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.
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.
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.
Right, so the question is "why not have side-by-side diffs". The fact that syntax highlighting would work is one obvious advantage. It also means that you can read the before/after code linearly without having to mentally apply the patch. It seems like an obviously better UI for understanding the effect of changes (although of course I don't have data to back that up).
I would like to see GitHub offer the option of seeing side-by-side. It can be helpful if you have a mess of tiny -/+ hunks right next to each other. But combined is definitely the correct default.
What do you mean? First off, you're making the assumption that your highlighting library gives you results that can be trivially split per-line (e.g. no styles cross line boundaries, line boundaries are easy to find, etc). I haven't worked with web highlighting libraries so I don't know if that's true. But let's say it is. Now how do you handle the problem I called out, where the context lines are highlighted differently in both versions? You only show the context lines once in a combined diff.
"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.
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.
"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!
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.
In practice, it's often good to have comments that explain what the code is doing, even if the code itself is quite understandable. It can be a lot quicker to read and understand a one-sentence English description than it can be to read 10+ lines of good code. If the code in question generally has accurate comments of this nature, then working with this code becomes far easier.
And then there are always those cases where rather poor code was written in the first place, it lacked comments, and then a maintenance programmer needs to figure out what it does in order to make some changes to it. Real-world constraints prevent the code from being completely rewritten, but adding comments explaining what it does can be invaluable for anyone else who will ever need to deal with the code.
It is not academic at all, but utterly practical. In your example of a 10+ line code block that is preceded by a comment, the correction is to extract that code into a subroutine and name it accordingly and maybe write actual documentation* for the usage of said subroutine.
Your second example is valid, though i have to admit i've not once been in that situation in my years of work, despite often working with legacy code, and suspect it's fairly rare.
* Note here that comments are not documentation, these are two different entities, one being aimed at the maintainer of a library, the other aimed at the user.
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.
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.
> It's fairly ironic that you've spent so many words re-iterating the argument that "code should be self-documenting".
It would be ironic if it was being argued that natural languages are bad. But that is not what's being argued, and the author of that comments was not trying to convey an algorithm to you.
> That's the job of a programmer, and if the programmer isn't doing their job [...]
This is puritanism. Just because it's work, doesn't mean it's useful.
Human communication is the rate-limiting process for all software teams. Individual productivity is almost entirely irrelevant, if your personal productivity means that you slow down ten other people.
As i said in a comment further down: Comments are not documentation.
Documentation explains how to use the exposed API to get the code to do something the user desires. It does however not describe what the code does, or why a specific bit of code is done in a certain way.
Comments do not concern themselves with the API, they also do not describe what the code does, that task is up to the code by way of structuring and proper naming of variables and functions.
What is left to the comments is to explain to the guy coming in afterwards why a certain bit of code is as it is when the code or the documentation cannot adequately explain its purpose explicitly or implicitly.
You're right that code doesn't compile itself, though. That's the job of the computer operator, who takes the code I write in my notebook and flips the corresponding switches on the computer. If the computer operator isn't doing their job, they probably shouldn't be working on a project with other people.
People are fallible. People make mistakes. People get bored. That's why we write tools to do our work for us. The way we avoid making mistakes is by making the mistakes impossible in the first place. This is why typing exists, because without static type checking, people will mix up their types. Yes, it's the job of the programmer to keep their types straight. The compiler doesn't care about types. So what? The whole point of tools is to make the life of the programmer easier, not by magically transforming them into perfect programmers who never make mistakes, but to have tools that avoid, check, verify and catch those mistakes.
Comments circumvent any such tools. Suddenly, you are back to banging rocks together.
The people who maintain the system are not helped by incorrect information. The information describing how the code works in comments is invariably incorrect. None of the tools we usually employ (unit tests, regression tests, compilation, etc.) apply to the comments, and describing the HOW of code in comments breaks the DRY rule unless the comments ARE the code.
Now, as I said, sometimes you need to describe intent. Most of the time, that is better done through liberal use of functions, purpose-specific types and function names.
For example: In C, there are multiple types of integers defined that all reduce to roughly the same types: size_t, ptrdiff_t, etc. Does the compiler care if the type is unsigned int or size_t? No. Apart from the portability reason for using these types, the other is to describe intent. A variable of the type size_t should store a size. Now, we could make the variable an unsigned int, and in a comment say that "this variable stores a size". But will this comment stay in sync with the code, when the variable later changes to a ptrdiff_t because it is now used to compare pointers? No. The comment won't get changed, because humans are fallible, and changing the comment would require making the same change in two places, one of which is ignored by the toolchain.
Yeah, I got it. Machines can't verify the documentation that humans write. It's not a subtle point.
Now, if the code were good enough to substitute for human-written documentation, you'd actually be addressing my argument. The people who argue that code is self-documenting tend to produce only badly documented code.
The way that comments stay in sync with code is that the developer keeps the comments up to date. It isn't that hard.
Documentation is something completely different from comments. Documentation is something you write for the interfaces you expose. This, I have absolutely no problem with. Interfaces are meant to be stable, they should be well defined, they should have human-friendly instructions and examples on use.
Comments in code? That's something completely different.
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."
No, they're arguing for documentation of intent rather than documentation of what the program does. What the program does is obvious if you have reasonably decent abstractions; what you intend to do is not so obvious.
Exactly. To me, even a comment expressing intent is usually a code smell unless it is in a function header. If the block of code is non-obvious enough that it needs an explanation, it should be its own named function, and the function name should describe its purpose.
Of course these are all SHOULDs and not MUSTs. There are always exceptions. But the general rule is definitely that comments are signals that something is broken.
It must depend on what programming culture you find yourself in, but I've seen more undercommenters than overcommenters, often with the excuse that the code is "obvious" or the comment would be literal.
Sometimes literal comments tell you things that you wouldn't pick up skimming the code: for(var i=0;i<length-1;i++) // skip the last element
Or, a comment could give a reason, like "iterate backwards because..."
Sometimes it takes half an hour to work what what two concise lines of code should say -- there may be something tricky going on, or you may be working around a bug in a driver or library or something -- and you should record what you were thinking.
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".
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').
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.
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.
> 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.
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).
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. "
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".
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.
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...
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.
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.
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.
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.
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.
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...
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.
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.
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.
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.
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.)
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.
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.
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.
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).
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.
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.
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.
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?
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.
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?
"x" is not always something which can be easily or fully explained in one to four words. And anything over four (short) words is typically getting too cumbersome as a variable name.
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".
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.
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.
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.
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.
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.
Since I'm sitting here with a voltmeter next to me, I'll point out that red==positive and black==negative.
The bigger point I'd like to make is that any talk of universal connotations of colors is probably wrong unless you've really studied it carefully.
For some history on why red means stop and green means go, see Straight Dope: http://www.straightdope.com/columns/read/437/who-decided-red...
Apparently it dates back to early railroads, where red meant stop, green meant caution, and white meant go. They discovered this wasn't failsafe when the red filter fell out, the train saw a white light and crashed. So they moved to green for go.
...no? As in China, they adopted red because of its preexisting immense popularity (well, for the USSR it seems they also drew on some "revolution is red" symbolism). Your causation is running backwards.
> The colour red has always been a positive symbol in the Russian culture. The word red (Russian: красный, krasnyy) is etymologically related with the Russian word for beautiful. This can also be seen in Moscow’s Red Square and the Russian Orthodox festivity, Red Easter.
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".
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
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.
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.
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...
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.
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.
I think the bigger problem with using red and green for commit changes is for the folks that are red/green colorblind.
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?
Do you map a 3D scene into 2D without any information about which aspect of the scene is important?
That's not the same. When you go from 3D to 2D you lose a dimension. Information is lost. When you map color spaces like I proposed you go from 1D to 1D, you're just compressing the data in that dimension. No information is lost (except because of the limits of numerical accuracy)
So you propose that colorblind people should make their OS turn all images, photographs and video into false color not correlating with reality because in some specific contexts color is used symbolically and it's important to distinguish between two colors? One option that might work would be a special drawing mode implemented in the OS graphics stack that did some mapping depending on what's configured in the accessibility settings; then applications could request that in the rare cases where it's important.
As a partially colorblind person (albeit easily capable of telling red from green here), while of course such a mode should not be required for programming, I wouldn't mind using it in general. The EnChroma glasses try to do this in real life, but they're expensive and only work in bright sunlight; if I can at least get the same for photos just by downloading something, it sounds interesting. (And probably already exists, so I should do some Googling.)
That's a really interesting idea. You'd want a fast toggle for it, so that you could use it primarily for browsing semantic content that uses colors, but not always for photographs or videos that represent the real world (unless those photos or videos contained such semantic content). It's not ideal, but much like assistive devices that translate vision to other nerve impulses (http://www.nei.nih.gov/news/briefs/weihenmayer.asp), it could be useful as a learned adaptation.
That said, it would also make sense for diff software in particular (as one of the most prominent software uses of red and green right next to each other for semantic purposes) to have an easily adjusted option for a different color scheme for the very common case of red/green colorblindness.
Which is weird when you think about it. red/green colourblindness is way more common in men and tech is quite male dominated.
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.
I do realize this. I also know someone that has had problems with it on github's diffs. I do think it would be better to use other colors to avoid the issue entirely.
It still work if you use different brightness for each color. Being colorblind doesn't mean you see red as white.
This is precisely why Wikipedia switched diffs from red/green to orange/blue.
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.
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.
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.
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.
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.
Right, so the question is "why not have side-by-side diffs". The fact that syntax highlighting would work is one obvious advantage. It also means that you can read the before/after code linearly without having to mentally apply the patch. It seems like an obviously better UI for understanding the effect of changes (although of course I don't have data to back that up).
Because side-by-side is very redundant, wasting almost half the screen on the exact same information.
You don't have to "mentally apply" a patch, just ignore some lines of a certain color.
I would like to see GitHub offer the option of seeing side-by-side. It can be helpful if you have a mess of tiny -/+ hunks right next to each other. But combined is definitely the correct default.
It's easy to process highlighting for the entire previous file plus the new file, and simply preserve it per line.
What do you mean? First off, you're making the assumption that your highlighting library gives you results that can be trivially split per-line (e.g. no styles cross line boundaries, line boundaries are easy to find, etc). I haven't worked with web highlighting libraries so I don't know if that's true. But let's say it is. Now how do you handle the problem I called out, where the context lines are highlighted differently in both versions? You only show the context lines once in a combined diff.
"Now how do you handle the problem I called out, where the context lines are highlighted differently in both versions?"
I'm not convinced "pick one" is a horrible choice.
"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.
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.
"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!
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.
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.
That is a very academic way of looking at it.
In practice, it's often good to have comments that explain what the code is doing, even if the code itself is quite understandable. It can be a lot quicker to read and understand a one-sentence English description than it can be to read 10+ lines of good code. If the code in question generally has accurate comments of this nature, then working with this code becomes far easier.
And then there are always those cases where rather poor code was written in the first place, it lacked comments, and then a maintenance programmer needs to figure out what it does in order to make some changes to it. Real-world constraints prevent the code from being completely rewritten, but adding comments explaining what it does can be invaluable for anyone else who will ever need to deal with the code.
It is not academic at all, but utterly practical. In your example of a 10+ line code block that is preceded by a comment, the correction is to extract that code into a subroutine and name it accordingly and maybe write actual documentation* for the usage of said subroutine.
Your second example is valid, though i have to admit i've not once been in that situation in my years of work, despite often working with legacy code, and suspect it's fairly rare.
* Note here that comments are not documentation, these are two different entities, one being aimed at the maintainer of a library, the other aimed at the user.
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.
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.
> It's fairly ironic that you've spent so many words re-iterating the argument that "code should be self-documenting".
It would be ironic if it was being argued that natural languages are bad. But that is not what's being argued, and the author of that comments was not trying to convey an algorithm to you.
> That's the job of a programmer, and if the programmer isn't doing their job [...]
This is puritanism. Just because it's work, doesn't mean it's useful.
Documenting your code is Puritanism?
Human communication is the rate-limiting process for all software teams. Individual productivity is almost entirely irrelevant, if your personal productivity means that you slow down ten other people.
As i said in a comment further down: Comments are not documentation.
Documentation explains how to use the exposed API to get the code to do something the user desires. It does however not describe what the code does, or why a specific bit of code is done in a certain way.
Comments do not concern themselves with the API, they also do not describe what the code does, that task is up to the code by way of structuring and proper naming of variables and functions.
What is left to the comments is to explain to the guy coming in afterwards why a certain bit of code is as it is when the code or the documentation cannot adequately explain its purpose explicitly or implicitly.
Um.
You're right that code doesn't compile itself, though. That's the job of the computer operator, who takes the code I write in my notebook and flips the corresponding switches on the computer. If the computer operator isn't doing their job, they probably shouldn't be working on a project with other people.
People are fallible. People make mistakes. People get bored. That's why we write tools to do our work for us. The way we avoid making mistakes is by making the mistakes impossible in the first place. This is why typing exists, because without static type checking, people will mix up their types. Yes, it's the job of the programmer to keep their types straight. The compiler doesn't care about types. So what? The whole point of tools is to make the life of the programmer easier, not by magically transforming them into perfect programmers who never make mistakes, but to have tools that avoid, check, verify and catch those mistakes.
Comments circumvent any such tools. Suddenly, you are back to banging rocks together.
Ah yes...the "humans make mistakes, so therefore we should completely ignore all concessions to the people who maintain the system" argument.
Those pesky humans will be much less problematic if they can't communicate in their imprecise meatspeak.
I don't think you understand what I'm saying.
The people who maintain the system are not helped by incorrect information. The information describing how the code works in comments is invariably incorrect. None of the tools we usually employ (unit tests, regression tests, compilation, etc.) apply to the comments, and describing the HOW of code in comments breaks the DRY rule unless the comments ARE the code.
Now, as I said, sometimes you need to describe intent. Most of the time, that is better done through liberal use of functions, purpose-specific types and function names.
For example: In C, there are multiple types of integers defined that all reduce to roughly the same types: size_t, ptrdiff_t, etc. Does the compiler care if the type is unsigned int or size_t? No. Apart from the portability reason for using these types, the other is to describe intent. A variable of the type size_t should store a size. Now, we could make the variable an unsigned int, and in a comment say that "this variable stores a size". But will this comment stay in sync with the code, when the variable later changes to a ptrdiff_t because it is now used to compare pointers? No. The comment won't get changed, because humans are fallible, and changing the comment would require making the same change in two places, one of which is ignored by the toolchain.
Yeah, I got it. Machines can't verify the documentation that humans write. It's not a subtle point.
Now, if the code were good enough to substitute for human-written documentation, you'd actually be addressing my argument. The people who argue that code is self-documenting tend to produce only badly documented code.
The way that comments stay in sync with code is that the developer keeps the comments up to date. It isn't that hard.
Documentation is something completely different from comments. Documentation is something you write for the interfaces you expose. This, I have absolutely no problem with. Interfaces are meant to be stable, they should be well defined, they should have human-friendly instructions and examples on use.
Comments in code? That's something completely different.
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."
No, they're arguing for documentation of intent rather than documentation of what the program does. What the program does is obvious if you have reasonably decent abstractions; what you intend to do is not so obvious.
vs
and in fact all that vs
Exactly. To me, even a comment expressing intent is usually a code smell unless it is in a function header. If the block of code is non-obvious enough that it needs an explanation, it should be its own named function, and the function name should describe its purpose.
Of course these are all SHOULDs and not MUSTs. There are always exceptions. But the general rule is definitely that comments are signals that something is broken.
It must depend on what programming culture you find yourself in, but I've seen more undercommenters than overcommenters, often with the excuse that the code is "obvious" or the comment would be literal.
Sometimes literal comments tell you things that you wouldn't pick up skimming the code: for(var i=0;i<length-1;i++) // skip the last element
Or, a comment could give a reason, like "iterate backwards because..."
Sometimes it takes half an hour to work what what two concise lines of code should say -- there may be something tricky going on, or you may be working around a bug in a driver or library or something -- and you should record what you were thinking.
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".
In other words, comments should explain why something was done and now how.
The author seems to brush off criticisms of his/her diff color ideas:
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').
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.
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.
> 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.
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).
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
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".
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.
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...
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.
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.
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.
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.
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.
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...
...we could write...
And that's just for starters!
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.
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.
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.
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:
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.
I think less code usually means less complexity. But less lines doesn't really correlate to less code.
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.)
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.
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.
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.
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).
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.
These "<blank> is wrong" or "you're doing <whatever> wrong" titles are tedious. Tell me about the better one you've written or STFU.
Yes, exactly! I am tired with these clickbait titles on HN. Come up a better title, damn it, this isn't DailyMail.
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.
sometimes, but not this time.
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.
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?
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.
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
So I guess we're just going to have a completely barren Javadoc then?
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.
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.
I don't think that in github the additions are green because are good, but because +=green and -=red
I missed where he suggests a better color scheme. He references it for pink commenting.
I wonder when literature will come standard with syntax highlighting.
The code itself is the "truth". The comments are commentary.
Which would you rather have bold and jumping out at you when skimming? Comments can be wrong because tweaks happen.
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?
If you have to explain what x is for with a comment, maybe x is a bad name in the first place?
"x" is not always something which can be easily or fully explained in one to four words. And anything over four (short) words is typically getting too cumbersome as a variable name.
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".
I'd much rather have the `x=5` jump out at me, because the example comment is entirely redundant. However, if the example was
then I would rather have the comment jump out at me.
"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.
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.
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.
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.
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.
Oh dear some one got out of bed the wrong side today :-)
Almost everyone intuitively knows that red = deletion and green = insertion. Nobody knows what yellow and blue refers to. So how is that more usable?
I'm pretty sure I learned that convention. Why would it be intuitive? What's the association between red/remove and green/add?
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.
Right, that's the point. Removal shouldn't be thought of as "bad" and the red/green == bad/good association does seem to be fairly deep.
I think that pretty much everywhere green==positive and red==negative.
Since I'm sitting here with a voltmeter next to me, I'll point out that red==positive and black==negative.
The bigger point I'd like to make is that any talk of universal connotations of colors is probably wrong unless you've really studied it carefully.
For some history on why red means stop and green means go, see Straight Dope: http://www.straightdope.com/columns/read/437/who-decided-red... Apparently it dates back to early railroads, where red meant stop, green meant caution, and white meant go. They discovered this wasn't failsafe when the red filter fell out, the train saw a white light and crashed. So they moved to green for go.
Although red was chosen in the case of electricity to signify danger, so it still has a "negative" connotation in terms of touching it.
Have you been everywhere? http://en.wikipedia.org/wiki/Color_in_Chinese_culture
Not even close; red is positive across large swathes of the world. There's a reason the USSR flag was solid red.
Socialism?
...no? As in China, they adopted red because of its preexisting immense popularity (well, for the USSR it seems they also drew on some "revolution is red" symbolism). Your causation is running backwards.
From http://en.wikipedia.org/wiki/Flag_of_the_Soviet_Union :
> The colour red has always been a positive symbol in the Russian culture. The word red (Russian: красный, krasnyy) is etymologically related with the Russian word for beautiful. This can also be seen in Moscow’s Red Square and the Russian Orthodox festivity, Red Easter.
Well. TIL. I thought it was the socialist flag.
Well, in western culture yes, definitely.
But the whole point is that code removal shouldn't be associated with being negative and so shouldn't be coloured red.
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".
Red means "stop," green means "go," is also learned behavior.
Yup. Especially because on a fruit it's exactly the opposite.
I've never learned that.
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.
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...
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.
For myself, and many others, green is green and red is also green. That likely presents a problem.
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.
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...
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.
Hey look, Uncle Bob said something about comments.
DELETE ALL COMMENTS AND CHANGE SYNTAX HIGHLIGHTING!