Do I have some weird rendering issue with this website, or do both of these snippets of code have terrible readability and highlighting? If I had to write code using an IDE or editor with this scheme I'd quit my career and go into small engine repair.
Nope, it looks the same to me and I have a screen with high contrast and high brightness. Both his examples are very hard to read. And I have done color blindness tests and know I am not color blind.
Another thing: I think one thing he is missing is how important it is to see at a glance where function definitions are and where possible early returns are. The first example highlights def (function definitions), return (possible early return) and the return type (arguably not that important in most cases).
Sorry about that! I built dark mode after writing this post and it broke the main text color inside the `pre`s, which should have been #222. Should be fixed now.
I totally agree with the sentiment of the author but the execution is really terrible. I'm not sure how the end product is at all better. It's appearing as like #CCC or #EEE on a white background. Screenshot: https://s3.whalesalad.com/images/hn/syntax.png
My favorite color scheme for a long time has been Made of Code, which I have slowly tweaked over the years. It has particularly great rendering of comments, where the line of the comment has a background color that takes up the entire row.
That theme looks very good from a practical standpoint, there's a lot of nicely contrasting colours. Do you personally find it aesthetically appealing though? I don't really.
For me aesthetics is a big factor. I've always liked having my computer set up the way I like. I don't have anything on my desk, so I think it's the equivalent of desk decorations. It makes me feel comfy and at home and thus more productive.
My favourite theme right now is Hopscotch. [0] I also find the reduced contrast also makes it easier to look at for long periods.
How is this gray on gray on black better than just coloring the method name differently? Seems to me the author just isn't happy with the color scheme, but discarding syntax highlighting alltogether seems like a step too far. Different colors definitely help me to quickly scan code.
this seems fundamentally similar to the idea of literate code, where the domain and context-specific information like comments (and in TFA, function and variable names) are put front and center.
This approach makes more sense to me though, as literate programming emphasises writing a book that incidentally contains source code, whereas the idea of valuable comments nowadays is closer to highlighting concerns or explaining functionality that isn't evident or easy to read in the code itself.
Or in other words; this sounds like a good idea! I wonder if it would help decrease the incidence of people ignoring and not updating comments though, as a developer's focus is often primarily on correcting the code and thus even with bolding the comments may end up falling into the same trap as banner blindness[1].
This largely seems like an issue with the author's IDE or theme, not an issue with syntax highlighting. I immediately assumed the first screenshot was what they were proposing since it's not like the syntax highlighting that I have used in vi, sublime, visual studio, or vscode. The actual proposal, to my eyes, removes highlighting entirely: I can't differentiate the shades well at all, and the "bold" commented text is even less visually distinct than in the original.
Semi-related: do folks actually use very low contrast themes like the one in the screenshot? My vision is better than 20 20 and reading light gray on white (or dark gray on black, for that matter) is a terrible strain on my eyes.
Edit: it appears the author has a dark mode theme on their blog which changes the colors of the screenshots
Yes, I use a low contrast theme, light grey on yellow.
My vim is Solarized based so I can invert colors at night and get more contrast by collapsing the RGB values into just red using NegativeScreen.
My bash is more custom: to be even lower contrast, I don't use colors except for when commands return with an error code. Instead, I use font attributes a lot (bold, italics, faint, etc) and I timestamp my commands so when I check my records I can easily find which parts took me the longest to think and do. The command I am typing has the current directory in bold to quickly remind me as I usually have several terminals opened.
> It seems those who write sparse comments want them to pop out of the screen, and those who comment more heavily like to provide a background hum of human commentary that's useful to read in certain contexts and otherwise easy to filter out.
This has slightly increased the number of comments overall and while I think quality has gone way up, I don’t want them more visible to the point of distraction.
Yep. Put me in the latter camp. If you made my comments more visable it would be highly distracting. Thinking about it like commentary is good because along with WHY comments over WHAT comments, I’ve been making an effort to describe INTENT for future readers (me).
I find that it usually falls down to a 'supra'/'infra' (or meta/within) dichotomy:
- the 'supra-comments' are essentially used as "section headers", "block title / description", i.e. structural markers. It's thus logical to want them standing out, like titles in a text document or section borders in a spreadsheet.
- the 'infra-comments' are the "explicited subtext", "block/line anotation", i.e. substantive but secondary content (usually discussion about the code, which may also be externalized to a spec doc). These are naturally dimmed, because they sit beneath or outside the primary substance, the code (inline or aside, as in text documents and web pages, or even hidden behind a toggle).
In that regard, languages with two syntaxes for comments (eg. block "/* ... */" and end-of-line "// ...") may be formatted by editors respectively "standing out" and "dimmed", giving this two-level comment schema to the developer.
I personally think the 'supra-comment' / structural approach is detrimental to readability (longer, bloat, to me it's ASCII art however you want to spin it), and that problem should be solved by organizing code better (block order, files), choosing more self-explanatory names for everything, and having proper external documentation (however succint, it's not optional and can't be substituted by comments).
In Intelli-j IDE's (WebStorm, PHPStorm, PyCharm etc) I've used a bit of a dirty hack to get as many different comment colours as I need. This involves re-purposing the "to do" highlighting feature.
I really like that idea of highlighting comments in different colours based on the prefix used. Very cool stuff, I will try to work that into my own workflow. Thank you for sharing!
The quality of the execution of the author's idea is a good guide to the quality of the idea itself.
In general, comments are not so informative and the code is self-documenting. ie., the code itself should be emphasized for comprehension.
The author misses the purpose of highlighting: to supply grammatical information where the language itself is deficient. Since we have plenty of experience with english grammar, we do not need help.
As with a lot of things, this is ultimately a matter of personal preferences, and the compiler could not care less about how your code is displayed in your editor. So, the question is not whether is's "backwards" or not, it's only a matter a finding the highlighting theme that subjectively suits you.
In my case, I prefer having the keywords highlighted and comments less visible than the code. Why? Because code is not something I read linearly. Having the syntactic markers highlighted helps me visually navigate from blocks to blocks. And it makes it much easier to spot missing curly braces, parentheses, etc.
Same preference here. I use highlighted keywords to navigate and find stuff quickly in files. Especially important is highlight of some keywords like "return" so I do not miss any early returns.
This is a good counter argument to the article. I know instantly what a switch statement does, but if I have big bold markers for where a switch and it’s cases are, that helps me jump to the block I’m looking for.
In the case of faint comments, I may need to slow down and actually read them if they’re a little less visible. I also know instantly that comments aren’t code and I don’t want all my code faint so just them being different from each other is enough for me.
Article makes good points but doesn’t seem like it’s for me.
I've seen a few editors[0] highlight certain words in comments like "TODO", "BUG", "FIXME", etc. It depends on the parser that the higlighter uses (some regex based may have limitations here), but it does exist.
[0] pycharm and vscode come to mind because I use them the most, but other that I don't recall also do it
Could 3D work here by having comments on a different focal plane than the actual code and then by switching the focus plane? This way one either looks at the comments sharply or at the code itself.
Scrolling “into” a function by depth should take you to its code then, I mean, I’m sure someone has tried this already but that seems like the next logical step.
Maybe what would work is some sort of show/hide comments. That is, at a keystroke be able to flip the contrast on comments to read them, then reverse it to look at the code.
I was just looking across the various editors/languages I use and though I have some variations, my main environments both have comments as green (on a dark background), and -- I suspect this is key -- nothing else uses green.
The contrast between hues has the enormous benefit of being both obvious and ignorable at the same time, depending on your frame of mind -- comments stand out, but it's also easy to think "brain: ignore anything green". I suspect this would work with any (primary?) color (though it will change what other colors are available for everything else)
I do have one environment (which I barely use) that has comments as a dull gray like the article has, and now that my attention has been drawn to it I realize I actually kind of hate it, and I'll probably end up changing the color scheme.
Intellij allows switching of theme with a keycombo, just clone your regular theme and edit it for focusing on comments. Same goes for other editors like vim where changing colours can be done fast.
I also use red color for global variables, helps me to detect if I forget a var or I made a typo, also I use different colors for local variables and method parameters.
Shouldn't the undefined globals be underlined by the linter already? Sorry I haven't done JS in forever, in Lua it will point out the unknown globals for me.
Not on my configuration, maybe it is done by default but I heavily modified my settings a long time ago, though in JS globals are valid, I get a lot of underlined for spelling, unused variables, possible uninitialized variables , I am trying to fix all the warnings but with JS dynamic ways I gave up, on PHP side I mostly fix all of them by defining the types in PHP Docs, handling all exceptions etc.
> Having the syntactic markers highlighted helps me visually navigate from blocks to blocks.
Exactly, and I second the personal preference point. It's not so much about highlighting specific things to call attention to them as it is about breaking up a homogeneous block of mixed text and whitespace into something structured and horizontally navigable.
Sadly this won't work when you read code online. GitHub shows comments gray, as well as StackOverflow. This makes one step in the right direction - movement to highlight the important things, rather than everything.
It seems that GitHub at least has CSS classes for many things (including the quotation marks around a string literal, it look like), so this allows customization.
I read this as the author advocating for some form of "comments first" development philosophy. As such, I'd like to submit this well known bit of work by Knuth for consideration (by anyone not already familiar with it):
If you are writing comments that aren’t worth reading, what is the point at all?
WHY not WHAT really helped me out. WHY is this thing here instead of WHAT it is can give a line like i++; a vastly different comment and implication for the reader.
I've people on previous teams that thought this, and their comments were consistently the ones that were the most out-of-date because they never valued fixing them. If you value comment accuracy during PR reviews then you're less likely to end up in that situation in the first place.
One fallacy I've seen is a reviewer only looking at the diff on Github, where a minor change in the middle of a function is made, and they don't expand the diff to notice that the new change completely invalidates a comment, params, call signature, return value..etc.
Maybe for internal comments. I like having different styles for docstring comments and other comments.
/** Frobnicate the weevil with the given ID and return 0 on success.
*
* Locks the weevil during frobnication, which may take a while.
*/
int weevil_frobnicate(const char *id);
The most important part here is the function definition and its types and parameters. Usually, when I'm looking for a function, the name and type is enough to find what I'm looking for. So I want the function declaration to stand out and the docstring to be faded.
The most intriguing version I've heard of this was also based on the feeling that it's already easy to scan for keywords and structure; they went a different direction, using color to make different things (especially confusable ones) look different: https://wordsandbuttons.online/lexical_differential_highligh...
I don't feel like I know how/if highlighting helps, so all I can really say is seems interesting.
I think some of the problems commenters are having with the color scheme are because the site has a dark mode and contrast might be worse when it's on. Maybe in that mode text colors meant for a dark background are still getting applied in the white-backgrounded code fragments.
We're really good at parsing code, thanks to languages designed to be easy to read and to our style guides (unless we don't have one, of course). Highlighting keywords is uselessly tiring for the eyes IMO.
What matters most is to separate code from what's not code and which doesn't follow the same rules: comments and string-like literals.
In my vim color scheme (https://github.com/Canop/patine) I only have three colors: one for code, one for comments, one for strings, and I find reading the code easier and less tiring this way.
Yes yes yes! For a long time this three color style was my philosophy. It's all you need.
I'm currently (with new laptop) doing a thing where I try to install/customize as little as possible. This means not using that philosophy, but not because it didn't work.
In eclipse comments such as TODO and FIXME were always bold.
The thing with important comments is that they are verbose, so they can span for example 5 lines (or 3 in this example). Because of this, they already have more attention.
I think most themes are pretty sane. There's a mixture of blue, darkblue and black for keywords and methods/vars. For contrast, strings and numbers are red and green.
Comments are green, so they stand out enough for me.
The comments are the most important part of the document, yet they are barely visible due to colour and contrast chosen by syntax highlighter. Example: https://learnxinyminutes.com/docs/csharp/
I totally agree, made a while ago a snippet for Atom with syntax highlighting based on a similar article [1] that will make comments bright pink (meta-tweet with the code in effect):
This sounds nice in an idealistic situation where comments are limited to identifying important gotchas, but in my experience there's way too many bullshit comments in most software
Highlighting is meant to create "visual handles" on the code so your eyes can quickly jump to beginning/end of function/loop to figure out the scope of the comment. If you put the comment first , it's like replacing the floor numbers in an elevator with the warning signs. At most , you'd highlight just the word "WARNING:" or "TODO:" etc. Anything more is clutter
The trouble is with the propagation of poor template systems auto generating relevant comments and new/junior developers writing comments that are just what the code does as opposed to functionally important.
Since this represents the bulk of comments most themes have started to contrast them out so that the actual code is more prominent
But to fix this the author should just find a better contrast for comments in their chosen theme so they are just as readable as code.
The idea you would make comments more prominent and the code harder to read leads me to believe they don't write much code.
Personally, I tweaked the default syntax coloring to deemphasise only punctuation (e.g. parentheses), and emphasise comments (for the reason outlined in the article). I don't think it's necessarily a good idea to deemphasize keywords - they often imply change in the evaluation semantics, so it's good to be able to spot them easily when scanning.
143 comments
[ 4.3 ms ] story [ 216 ms ] threadhttps://imgur.com/a/vS2EldV
Edit: Yep, dark mode mangled the code snippets.
Another thing: I think one thing he is missing is how important it is to see at a glance where function definitions are and where possible early returns are. The first example highlights def (function definitions), return (possible early return) and the return type (arguably not that important in most cases).
Try turning them off, it'll look much better.
It overrides the GTK theme used to render page content and still allows to use a dark theme (or whatever you want) for UI components.
My favorite color scheme for a long time has been Made of Code, which I have slowly tweaked over the years. It has particularly great rendering of comments, where the line of the comment has a background color that takes up the entire row.
Example 1: https://s3.whalesalad.com/syntax/made-of-code-tweaked.png
Example 2: https://s3.whalesalad.com/syntax/made-of-code-tweaked-2.png
Theme file (Textmate/Sublime): https://s3.whalesalad.com/syntax/whalesalad-2.tmTheme
For me aesthetics is a big factor. I've always liked having my computer set up the way I like. I don't have anything on my desk, so I think it's the equivalent of desk decorations. It makes me feel comfy and at home and thus more productive.
My favourite theme right now is Hopscotch. [0] I also find the reduced contrast also makes it easier to look at for long periods.
[0]: https://github.com/idleberg/Hopscotch
This approach makes more sense to me though, as literate programming emphasises writing a book that incidentally contains source code, whereas the idea of valuable comments nowadays is closer to highlighting concerns or explaining functionality that isn't evident or easy to read in the code itself.
Or in other words; this sounds like a good idea! I wonder if it would help decrease the incidence of people ignoring and not updating comments though, as a developer's focus is often primarily on correcting the code and thus even with bolding the comments may end up falling into the same trap as banner blindness[1].
[1] https://en.wikipedia.org/wiki/Banner_blindness
Semi-related: do folks actually use very low contrast themes like the one in the screenshot? My vision is better than 20 20 and reading light gray on white (or dark gray on black, for that matter) is a terrible strain on my eyes.
Edit: it appears the author has a dark mode theme on their blog which changes the colors of the screenshots
I think the default highlighting is fine because it's what's best for beginners, highlighting language keywords and such.
My vim is Solarized based so I can invert colors at night and get more contrast by collapsing the RGB values into just red using NegativeScreen.
My bash is more custom: to be even lower contrast, I don't use colors except for when commands return with an error code. Instead, I use font attributes a lot (bold, italics, faint, etc) and I timestamp my commands so when I check my records I can easily find which parts took me the longest to think and do. The command I am typing has the current directory in bold to quickly remind me as I usually have several terminals opened.
Here is what my bash (where I spend the most time in) and vi looks like: https://raw.githubusercontent.com/csdvrx/sixel-tmux/master/s...
My bash has changed to match vi: the # prompt and red error codes now use the background color with: \e[2;48;2;215;215;175m\]#[\e[0m\]
Negative Red=win+alt+F9 { -0.3, 0.0, 0.0, 0.0, 0.0 } { -0.6, 0.0, 0.0, 0.0, 0.0 } { -0.1, 0.0, 0.0, 0.0, 0.0 } { 0.0, 0.0, 0.0, 1.0, 0.0 } { 1.0, 0.0, 0.0, 0.0, 1.0 }
Example on: https://raw.githubusercontent.com/csdvrx/sixel-tmux/master/s...
For the last 6 years I use three colors for comments: https://i.imgur.com/vU783Xo_d.jpg?maxwidth=640&shape=thumb&f...
If you have a configurable editor you can find more useful things to highlight in the code as well: https://www.reddit.com/r/programming/comments/1w76um/comment...
https://i.imgur.com/vU783Xo.jpg
This has slightly increased the number of comments overall and while I think quality has gone way up, I don’t want them more visible to the point of distraction.
Yep. Put me in the latter camp. If you made my comments more visable it would be highly distracting. Thinking about it like commentary is good because along with WHY comments over WHAT comments, I’ve been making an effort to describe INTENT for future readers (me).
- the 'supra-comments' are essentially used as "section headers", "block title / description", i.e. structural markers. It's thus logical to want them standing out, like titles in a text document or section borders in a spreadsheet.
- the 'infra-comments' are the "explicited subtext", "block/line anotation", i.e. substantive but secondary content (usually discussion about the code, which may also be externalized to a spec doc). These are naturally dimmed, because they sit beneath or outside the primary substance, the code (inline or aside, as in text documents and web pages, or even hidden behind a toggle).
In that regard, languages with two syntaxes for comments (eg. block "/* ... */" and end-of-line "// ...") may be formatted by editors respectively "standing out" and "dimmed", giving this two-level comment schema to the developer.
I personally think the 'supra-comment' / structural approach is detrimental to readability (longer, bloat, to me it's ASCII art however you want to spin it), and that problem should be solved by organizing code better (block order, files), choosing more self-explanatory names for everything, and having proper external documentation (however succint, it's not optional and can't be substituted by comments).
https://i.imgur.com/EKiVA0X.png
By the way @akkartik, it looks like your imgur link goes to the thumbnail rather than the image :)
In general, comments are not so informative and the code is self-documenting. ie., the code itself should be emphasized for comprehension.
The author misses the purpose of highlighting: to supply grammatical information where the language itself is deficient. Since we have plenty of experience with english grammar, we do not need help.
In my case, I prefer having the keywords highlighted and comments less visible than the code. Why? Because code is not something I read linearly. Having the syntactic markers highlighted helps me visually navigate from blocks to blocks. And it makes it much easier to spot missing curly braces, parentheses, etc.
In the case of faint comments, I may need to slow down and actually read them if they’re a little less visible. I also know instantly that comments aren’t code and I don’t want all my code faint so just them being different from each other is enough for me.
Article makes good points but doesn’t seem like it’s for me.
[0] pycharm and vscode come to mind because I use them the most, but other that I don't recall also do it
edit: a couple of typos
I have BENFIXME and a git hook to prevent ever commiting it, handy for when I want to not forget to come back to something.
The contrast between hues has the enormous benefit of being both obvious and ignorable at the same time, depending on your frame of mind -- comments stand out, but it's also easy to think "brain: ignore anything green". I suspect this would work with any (primary?) color (though it will change what other colors are available for everything else)
I do have one environment (which I barely use) that has comments as a dull gray like the article has, and now that my attention has been drawn to it I realize I actually kind of hate it, and I'll probably end up changing the color scheme.
Exactly, and I second the personal preference point. It's not so much about highlighting specific things to call attention to them as it is about breaking up a homogeneous block of mixed text and whitespace into something structured and horizontally navigable.
https://en.wikipedia.org/wiki/Literate_programming
IME that gives all a starting point or base line for discussions around "what can more/good/better comments and support for documentation do for me".
WHY not WHAT really helped me out. WHY is this thing here instead of WHAT it is can give a line like i++; a vastly different comment and implication for the reader.
As a result, comments lie and can’t be trusted, and the only source of truth is actual code.
One fallacy I've seen is a reviewer only looking at the diff on Github, where a minor change in the middle of a function is made, and they don't expand the diff to notice that the new change completely invalidates a comment, params, call signature, return value..etc.
I don't feel like I know how/if highlighting helps, so all I can really say is seems interesting.
I think some of the problems commenters are having with the color scheme are because the site has a dark mode and contrast might be worse when it's on. Maybe in that mode text colors meant for a dark background are still getting applied in the white-backgrounded code fragments.
What matters most is to separate code from what's not code and which doesn't follow the same rules: comments and string-like literals.
In my vim color scheme (https://github.com/Canop/patine) I only have three colors: one for code, one for comments, one for strings, and I find reading the code easier and less tiring this way.
I'm currently (with new laptop) doing a thing where I try to install/customize as little as possible. This means not using that philosophy, but not because it didn't work.
https://github.com/mikelward/conf/blob/master/vim/colors/bas...
And a similar theme I wrote for vscode.
https://marketplace.visualstudio.com/items?itemName=mikelwar...
The thing with important comments is that they are verbose, so they can span for example 5 lines (or 3 in this example). Because of this, they already have more attention.
I think most themes are pretty sane. There's a mixture of blue, darkblue and black for keywords and methods/vars. For contrast, strings and numbers are red and green. Comments are green, so they stand out enough for me.
The comments are the most important part of the document, yet they are barely visible due to colour and contrast chosen by syntax highlighter. Example: https://learnxinyminutes.com/docs/csharp/
https://twitter.com/FPresencia/status/1133733608785473536
For copy/paste (in Atom -> Stylesheet...):
[1] https://jameshfisher.com/2014/05/11/your-syntax-highlighter-...