Syntax highlighters are wrong
medium.com
medium.com
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.
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.
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.
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.
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.
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.
You don't have to "mentally apply" a patch, just ignore some lines of a certain color.
I'm not convinced "pick one" is a horrible choice.
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.
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.
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!
- 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.
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.
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.
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.
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 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.
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.
Those pesky humans will be much less problematic if they can't communicate in their imprecise meatspeak.
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.
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.
Comments in code? That's something completely different.
And please don't say, "That's right, Haskell" or "Yes, my favorite LISP."
// Increase the counter by one
counter++;
// Log that a user has viewed the page
counter++;
fn logHasViewed() {
pageViewCounter++;
}
logHasViewed();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.
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.
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".
[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.]
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').
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.
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 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).
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".
Sure, take out those comments, but then his next blog post would be about the lack of decent documentation available for various projects...
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.
protected HashMap children = new HashMap();
protected int backgroundProcessorDelay = -1;
protected LifecycleSupport lifecycle = new LifecycleSupport(this);
protected ArrayList listeners = new ArrayList();
protected Loader loader = null;
protected Log logger = null;
protected String logName = null;
protected Manager manager = null;
protected Cluster cluster = null;
protected String humanReadableName = null;
protected Container parent = null;
protected ClassLoader parentClassLoader = null;
protected(defaultInitialValue: null){
HashMap children = new HashMap()
int backgroundProcessorDelay = -1
LifecycleSupport lifecycle = new LifecycleSupport(this)
ArrayList listeners = new ArrayList()
Loader loader
Log logger
String logName
Manager manager
Cluster cluster
String humanReadableName
Container parent
ClassLoader parentClassLoader
}
>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.
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.
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 !!!!! //
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.
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.)
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.
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.
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).
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.
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.
So much for "virtually every highlighting scheme".
//Set x to be 4
x=5;
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".
// removing this will cause a segfault because ...
x=5;
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.
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.
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.
But the whole point is that code removal shouldn't be associated with being negative and so shouldn't be coloured red.
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.
red - deletion of genetic sequence blue - insertion of genetic sequence
1: https://www.iscaconsortium.org/index.php/the-news/95-the-mea...
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.
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...
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.
DELETE ALL COMMENTS AND CHANGE SYNTAX HIGHLIGHTING!