Syntax highlighters are wrong (2014) | Hacker News Reader

Syntax highlighters are wrong (2014)

jameshfisher.com

233 pointsTuringTest170 comments

> I have identified two important kinds of value judgment - important vs. unimportant, and success vs. failure. I have showed how these judgments are made by our existing code highlighting themes: comments are hidden as unimportant, and deletions are displayed as errors. These judgments intrude on and influence our own thoughts and judgments.

I find this whole article highly speculative. It's based on principles the author adapted from somebody who wrote a book about how to write code, but I doubt they really influence or apply to lots of people.

I don't value comments less or more because they are cursive or light grey. Code highlighting should help to easily distinguish between different parts of the code, but as unobtrusive as possible. This is not an easy task especially with the limited set of options you have for plain text.

I also don't perceive removals in diff view as "bad" because they are red but as "look here, could be important".

So this article is about the feelings of the author, not so much about facts.

Agreed. If I'm looking for comments, the washed out look is easy to pick up. Also. many people don't or can't follow clean code.

Could you imagine the mess if you were writing an API that required JSdoc with the author's proposed highlighting scheme? Or Golang's enforcement of comments on public functions?

Agreed about the red. I find it deeply satisfying.

I also don't perceive removals in diff view as "bad" because they are red but as "look here, could be important".

That's really the problem with using red for deletes in a diff. Red implies that the deleted lines are more important than the added lines, and that's wrong. You shouldn't (and can't really) focus exclusively on the deleted code. Breaking the 'red = important' connection and using a color scheme that gives equal weight to the removed and added lines may well work better once you get past how weird it is.

> Red implies that the deleted lines are more important than the added lines

I've never gotten that impression. I and my coworkers & classmates usually highlight text using the standard yellow highlighter, occasionally using other snazzy highlighter colours - red sometimes included, but usually not.

The associations that leak in from other domains are green=good/go, red=bad/stop. It's very easy to mentally remap the colours to the intuitive green=new, red=old.

Agreed. Comments aren't about important vs. unimportant, they're about words that are executed vs. words that are documentation. Even commented out code, in the rare cases when it's a good idea to leave around, is a form of documentation. It's not code any more if it's not running.

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

This is strongly and patently not true. Here in Japan the available taxi is in Red while the taken one is in Green, and there are many more similar examples. Admitedly it's mixed, because traffic lights are still red to stop and blue to cross. Wait blue? There was no distinction in Japan between green and blue back in the day and that still remains. Colors are very much culture-dependent, and saying otherwise is ingenuous at least and misleading at best.

It's true in the places where they decided to use green for adding lines and red for removing them.

That said I don't think it matters. The benefit of not making removing lines look like a bad thing is definitely outweighed by the cost of not making it obvious which colour means which. Was olive for lines added? I can never remember...

You have a point that colour perception is culturally modulated, but I'd argue that the original point still stands in the modern world (which is what's relevant to the discussion of syntax highlighting): the majority of people who look at code will sooner associate red with bad than with good, and this association has become self-sustaining (much like the widespread adoption of qwerty-like keyboards).

Your example of Japanese taxi signs using red to signal availability is an interesting but rare exception to the general rule across the industrialized world that red={warning, danger, no, stop, delete}, and green={safe, good, yes, go, maximize}. For this example, there are many counterexamples. After all, Japan uses red=stop, green-blue=go on all traffic lights, railways, shipping, and aviation, in accordance with international conventions.

Yes, colours are very much culture-dependent, but red=bad and green=good (or green-blue for cultures that don't distinguish these two colours) has been intentionally adopted across cultures for generations -- dating back to shipping and train signals, if not much earlier to verdant countrysides versus blood, fire, etc.

Humans have been trained by the evolution to spot red fruit on green background. This way red is "loud" and green is "quiet". It makes perfect sense then to announce free taxies in a loud voice then.

But you can turn this around if you consider "loud" = "ERROR; DANGER; STOP (found fruit?); NO" and "quiet" = "yes; safe; good; continue (no fruit; keep looking?)".

In Chinese stock market, Red means the stock is up and green means it’s down. If you have an iPhone, try setting the language to Chinese and open the Stocks app. Red has always been considered an auspicious color in Chinese culture. It’s the theme color of weddings and Chinese New Year.

And what colour means stop/error in China's traffic lights, rail networks, shipping lanes, and aircraft?

That is not exactly relevant.

In China it is understood that red color is used to indicate STOP because it has the greatest wavelength and is therefore more visible in inclement weather.

In addition, color code for traffic light is fixed by international convention and it’s not like China can choose whatever it wants.

My point is, culture has nothing to do with the choice of stop light color in China

> My point is, culture has nothing to do with the choice of stop light color in China

That's exactly my point as well. The article mentioned that the association between red and "bad" stuff (stop, error, etc.) is cross-cultural. Someone replied vehemently denying that, but the fact is that red={stop, error, bad, ...} is a long-standing international convention that does supersede regional cultural effects.

> In addition, color code for traffic light is fixed by international convention and it’s not like China can choose whatever it wants

China can choose whatever they want, but don't.

Many countries have not signed the Vienna Convention on Road Signs and Signals. For example China, Japan and the United States have not signed the convention.

Japan is a good example: "It is a near universal constant when driving: red means stop, and green means go. So fundamental is this dynamic that it is codified in international law under the Vienna Convention on Road Signs and Signals, which has been ratified by 74 countries. Why, then, does Japan — not a signatory to the Convention —seem to buck the trend with its blue/green traffic signals?" https://www.atlasobscura.com/articles/japan-green-traffic-li...

I actually just tried this out- you need to change the region to China Mainland actually, not the language.

Entire countries like France do not use qwerty, and in Japan the taxi light is not an exception, rather it is fairly common. The traffic light IS the exception here, and it is definitedly not accepted that red=bad and green=good here! If anything, I'd say that red here represents the primary action.

Hence my mention of "qwerty-like." France's AZERTY is a variation on qwerty (https://en.wikipedia.org/wiki/AZERTY#History).

In modern UX/UI, red is universally understood to mean delete, close, stop, error, and similar "bad" or destructive things. If you localize OS X to Japanese, does the "close window" button change from red to something else? If you localize GitHub to Japanese, does its irreversible repo deletion confirmation prompt appear in green? Is the "proceed to GitHub" button at https://github.co.jp/ green or red?

In practice there are 3 types of comments:

- documentation, that should be parsed by some external tool (javadoc, godoc, etc.)

- warnings in the code, like the "this call is very important because of..." example from the article

- commented out code.

I want warnings to sitck out, but I don't want doc to stick out.

Commented-out code should not exist, granted, but in the meantime I don't want it to stick out either. If I'm commenting-out my own code, that's because I'm trying to understand some issue, so please don't distract me. I'll remove it later, I promise.

> If I'm commenting-out my own code, that's because I'm trying to understand some issue, so please don't distract me. I'll remove it later, I promise.

This is where multiple rulesets could come in handy. Your editor which you're using for debugging should keep the commented-out code nice and subtle, but when you go to commit it should be bright purple with yellow spots.

You could actually do exactly that in VSCode. I might have to try making it.

Why "require" documentation comment blocks to be parsed by external tools and read elsewhere? It's perfectly fine to have big blocks of documentation comments right in the code, and to be consumed there.

The current "fashion" of making comments as unreadable as possible in most syntax highlighter themes is indeed my main gripe with them.

Comments don't have to particularly stick out, but it would at least help to make them as readable as the actual source code.

Ye. Reading eg. Javadoc verbatim is awefull.

There are nice doc generators that allow natural language with markup only for special attributes.

> It's perfectly fine to have big blocks of documentation comments right in the code, and to be consumed there.

If you need to read the source code to use a library, something is wrong with that library.

(On the other hands it is fine to document local functions, but it doesn't need to be a verbose documentation comment.)

Quite the opposite, a library can be understood fast and in depth when the code and its comments are readable directly, skipping the indirection layer of any external documentation.

"in depth" is probably correct, but "fast" depends.

I tend to classify libraries into two classes, something I can obviously make but I don't have to, and something I would have to try hard (or even be impossible) to make it. You can't quickly understand the second class of libraries by reading the code. If you need a concrete example, take miniSAT [1] as one.

[1] https://github.com/niklasso/minisat/blob/master/minisat/core...

I'm thinking of examples like this:

https://github.com/nothings/stb/blob/master/stb_image.h

It's a complete image loader library in a single header. This header contains everything I need to use that library: the entire documentation, the license, public API declarations and finally the implementation source code.

I can read this file from top to bottom to know every little detail about this library, or I can stop somewhere inbetween (for instance when I only want to know how to use the library and what the API looks like, but I'm not interested in the implementation details).

First, I consider a single header library as a symptom from the lack of fine package managers for C and not as a feature. Such a form should not have been a norm at all.

Also note that stb_image is extremely stateless. The documentation is not a must for stateless APIs because it is relatively easier to infer from the signature (of course you need to learn the convention, for example, to see that `int x, int y` etc. are out parameters and should not be NULL though). But many other libraries need states, and a proper documentation is required.

So a good syntax highlighter should differentiate between these different kinds of comments. Grey out the javadoc stuff, but emphasize the informative and warning comments.

And I think it could be really useful and commented-out code would still be highlighted, but in a washed out way or some other way that emphasises it's not currently active code.

> So a good syntax highlighter should differentiate between these different kinds of comments. Grey out the javadoc stuff, but emphasize the informative and warning comments.

But those who write Javadoc well, will put important stuff in there. And those who write non-Javadoc comments badly, will put useless stuff there.

Looks like an AI-complete problem to distinguish important from unimportant comments...

There’s fourth the most important and imho the only important type of comment: a comment which helps understanding why code does what it does when it is not expressed in code itself.

E. g.

// do two iterations of bubble sort before // falling back two qsort // because 99% of data comes almost sorted

This information cannot be obtained by reading function body, thus it should be added to comment.

> Commented-out code should not exist, granted .... I'll remove it later, I promise.

In my opinion, you should never commit commented out code. Here's why:

1. Commented out code, just confuses and clutters people's interpretation of the project. It's meaning is not clear as it's not a functioning part of the system.

3. It can incorrectly inflate the apparent complexity of a project.

2. It reduces the impact of meaningful comments, so people end up ignoring all comments.

Commit a working-state of the system only. If you're working through a problem, save the functions without commenting them out and completely remove them when you don't need them... you can always go back and find it in the source-control later when you need it.

Also, one of the first things I do when coming onto a new project is (switch to a new branch) and remove all the dead code.

>> Commented-out code should not exist, granted .... I'll remove it later, I promise.

> In my opinion, you should never commit commented out code.

But the editor works on uncommitted code, too. GP doesn't want to be distracted by that.

> ... so please don't distract me. I'll remove it later, I promise.

It could mean people are literally looking over his shoulder at his screen and complaining. But to me, it implies that commented code is becoming part of the project source...

Thanks to distributed version control, you can commit all sorts of trash in your own branch while figuring things out. These commits should not clutter the project source, though if you like hoarding data like I do, you might still preserve this history somewhere else in the repository.

No, I'm talking about my own "private" code in my own editor. This is a conversation with my editor while I'm "in the zone". I (usually) don't commit commented-out code, for the reasons you mentioned above.

Ah I see the context now, sorry for assuming the intent.

How about code that dumps internal state to logs or standard out and really helps when debugging a unit test?

Don't want it running in production because it's a whole bunch of database queries that just tax the DB, and production volumes are bigger than test cases.

Dead code, but useful dead code.

(Whether excluded by switch or comment makes little odds; it has no value in being turned on dynamically, so it's statically verifiably dead.)

Maybe we should have a second kind of comment, for code you don't want to be run. Then it can be highlighted (or the opposite) differently and not pollute real comments.

> 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.

Red is a lucky/auspicious/'good' colour in China and parts of S/SE Asia. Red dresses, for instance, are traditional at some cultures' weddings.

Even in the US red isn't "bad". Examples being the red sports car, the traditional colour of barns, Protestant church doors, power-on lights on devices, red roses, and Valentine's day hearts.

I think the author is just conflating the commonality of traffic symbols as some deep-rooted, cross cultural phenomena.

I'd also object to "stop", as in at a traffic like, connoting "bad". A break from driving is often welcome!

> Even in the US red isn't "bad"

*always "bad". Some bad examples, red is associated with the evil political party i.e. Republicans.

The obvious problem is that comments have different semantics: They are used for additional information -- this is what Javadoc or Python's embedded documentation is for. Note that Javadoc (or Doxygen) solves this problem with another syntax:

    /* regular comments */
    // regular comments

    /** Javadoc comments */
    /// Javadoc comments

This convention is understood by many syntax highlighters.

However, regular comments are frequently used to "comment out" code snippets while working on code. I assume "graying out" follows the "commenting out" idiom.

The colouring preferences of visual diff's are a completely different topic. IMHO, red/green is just a widespread convention. Of course it mentally supports the bad/good association, which is seldomly correct (even in other contexts as code).

I've come around to the idea that you should never comment out code, you should use #if #endif. And if the code has been replaced then you should include the new and old code as follows.

   // comment that explains what the change was and why we are keeping the old code around. 
   // Date we made this change.
   #if true 
      new code 
   #else 
      old code 
   #endif

That's a good idea, but it requires the language ecosystem to be shipped with that kind of preprocessor. In the given examples (Java and Python), that's not the case. And the proposal fails if you comment out non-compiling code without the context switch to a preprocessor:

  if false:
     this(does not compile)
  else:
     that.might("be")

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

I see this the opposite. I love commits with tons of red, and dislike commits with lots of green. Green means more reading and trying to figure out what this new code does, whereas lots of red with a little green means someone cut away all the old ugly code and replaced it with something better.

If the colours were to be reversed, I would get really confused. I guess I've sufficiently internalised the current usage, and I'm fine with it. I suppose I should ask a younger programmer how they view the red and green in commits.

Edit: His "neutral" addition/deletion colours don't really work for me. They don't have the clear association that red/green has. And the red = bad, green = good works fine if you want to remove bad code and add good code. It's never that simple, obviously, but the colour work very well for me.

The colours don't work so well for red/green colour blindness, obviously. That's a good reason to use something else. But maybe every highlighting tool needs to be configurable to use the colours that work best for you. Most are, but is github?

Just change your damn color scheme to what you want and get on with the actual work. They're not "wrong", you're just being dramatic.

The main thrust of this article seems to be more "crufty comments are wrong" rather than "the syntax highlighter is wrong." (Although when I was a fresh graduate my boss suggested setting comment colour to light grey to make it easier to read the code... which it really did because 90% of the comments were just commented-out lines of code from experiments that never got cleaned up. shudder)

For the diff colouring, I've always read red lines as being "bad" in the sense of "these ones had to go" (not in the sense of "these changes are wrong") and green lines being "good" in the sense of "these are what they should have been."

Which is shame, because as many know who have written a syntax highlighter for a language, there seem to be no real science or rules for what gets highlighted and what doesn't; and which do colors do we apply for each? Do operators get highlighted? What about function names? Variables? What about parens? Do we give [ ( and { different colors? Some lisp highlighters give each paren a different color so that it looks like a rainbow. Is this a good idea or a bad one? Do we give + - * / the same colors? Any color at all? The same color as =? It seems like everything is done based on intuition rather than any methodology. I'd be interested to see an article that answers some of the above questions.

> Martin writes that ‘the proper use of comments is to compensate for our failure to express ourself in code.’ It’s there to shout out about something that the code fails to tell you. The comment needs some help to distinguish itself from the surrounding code and say, ‘hey, I’m important!’

This is exactly backwards in my experience. Comments can lie. Computers don't execute comments. When reading code for understanding, you need to treat the comments as at best a guide and read the code first. Sure, there are rare cases where an algorithm is so subtle it needs to be explained via other media, but even then a simple link to documentation or a textbook reference is IMHO a better guide. Comments are awful in practice. Stay away.

Whether that has anything to do with syntax highlighting is an open question.

On the other hand, one of the most common reasons for comments to lie is that the code is updated and the comment is not. If comments were highlighted to grab attention more strongly, perhaps that would happen less often.

Perhaps, but I rather doubt it. Despite the link's claims, comments are noise for precisely the reason GP mentioned. Because comments can (and often do) lie, I only ever read comments after I thoroughly understand what the code is doing. If I already know why it's doing that thing, then the comment is (for me in that moment) superfluous and I'm unlikely to want to bother paying it any attention at all. As such, no matter how distracting you make the color scheme for comments, my brain is eventually going to learn to filter them out by default.

Was javadoc the first tool that encouraged, almost forced, the redundant comment?

Instead of comments just to make clearer the intent of the code, now we had highly repetitive comments in boilerplate format that would add nothing to already clear code.

As comments went from being one thing "make intent clear, shout why something happens" to multiple things "generate docs" + "pass commit linting"... the value of a comment diminished fast and so it isn't surprising to me that syntax highlighting downplays the comment.

What is surprising is that we haven't yet defined multiple types of comment: 1 for documentation, 1 for clarity. Or that we haven't determined the context of a comment and chosen to highlight depending on that context.

>What is surprising is ... we haven't determined the context of a comment and chosen to highlight depending on that context.

My syntax highlighter does do this, for every language I can think of - and so does essentially every code editor software I can remember using. The most popular editors even have the power to collapse doc comments, and I believe some do by default.

I have never cared much about syntax highlighting. I find it distracting, especially when typing. Type opening quotes and your whole buffer turns "stringy" until you type the closing quotes. It's enough to induce epileptic seizures.

In my editor I switched off all my syntax highlighting except for two things: all comments are in bold (for I agree with the author that comments should be in your face) and comments marked with "TODO" are in pesky red, nudging me to fix the marked issue ASAP.

I like basic syntax highlighting, but I'm not picky about the coloring other than it being Solarized in the cases where I can choose. I like that different things are highlighted differently: it's a simple semantic bug checker ("Why is everything red? Oh, I forgot to close that quote.").

The quote issue is quite true, although some editors have "smart" input modes which will introduce open+close syntax at the same time, and "step over" the close syntax when typed (rather than duplicating it).

For example in Emacs https://www.emacswiki.org/emacs/AutoPairs

Similarly, I made a custom colour scheme that only highlights comments and TODOs: https://imgur.com/zp4GarX

I feel like my ability to read code improved from disabling any other highlighting, but I have no real way of testing whether that's true.

Is that 0x1_0000 a typo? Shouldn't it be 0x1_000 or 0x10_000 instead?

It makes sense to group hexadecimal numbers by two (nibbles).

In this case 0x1_0000 is the least-significant bit of the third byte.

If that's a bit flag encoded in a 32bit value, I also like 0x0001_0000 for clarity.

Note that it's not my code, nor am I familiar with it. I just had it lying around on my disk to try out Alacritty.

Here's the line in question: https://github.com/jwilm/alacritty/blob/master/alacritty_ter...

I agree 0x1_000 or 0x10_000 would make more sense, but it doesn't look like the actual value used is hugely significant.

My syntax highlighter is not "wrong", it just doesn't match with the relative importances that the author of this article has assigned each thing (of course, using their cultural bias…).

The real problem with red/green diffs is that up to 10% of men are red-green colorblind. It's a real accessibility issue.

Blue yellow is also a form right? What is a safe color blind-friendly pair of contrasting colors?

The interwebs is full of examples (search for categorical color palette colour blind). But colorbrewer [1] is well known. And this [2] article "Color Universal Design (CUD) - How to make figures and presentations that are friendly to Colorblind people" gives loads more information.

[1] http://colorbrewer2.org/#type=qualitative&scheme=Paired&n=3

[2] http://jfly.uni-koeln.de/color/

Red and blue (like Jenkins, but that seems to be coincidental).

That said, if you think color accessibility is about picking the right categories of colors you have a long way to go.

The important thing is that the colors need to have sufficient contrast beyond mere hue. Light green and deep red is fine for me as a strong deutan (i.e. severely green blind) even though there are combinations of "red" and "green" that are practically indistinguishable for me.

Hmm, red-and blue makes sense, given that they are the furthest apart physically.

Obviously accessibility is about more than picking colors, but if a complaint is 'this is a bad color pair' it is interesting to know what is a better pair.

As for contrast beyond hue, does that include saturation? Because keeping luminance constant is an important part of keeping an interface legible.

I'd say a red-blue default with full configurability might be the best approach.

Red and blue are not ”the furthest apart”. Red and cyan, or blue and yellow, are complementary (180° separated on the color wheel). But color perception is more complicated than that.

I believe something like orangish red and bluish green are distinct enough to most people with a red-green deficiency (including myself). The difference in ”blue content” makes them distinguishable.

The actual wave-lengths are the furthest apart. Whilst that is not perceptually relevant, it is relevant to what happens when color-receptors fail. That is, as long as you have two different color receptors that respond differently to different wave-lengths, those will receive different signals from red and blue light.

The wavelengths that are furthest apart are red and violet. Which perceptually are close together, for red-green blind as well. But what does matter is picking the colors based on the corresponding receptors' peak sensitivity. The L receptors are most sensitive to red, and the S receptors to blue, so in that sense you're right. (Red-green blind or weak people lack the M receptors of have anomalous versions, respectively.)

About 1 in 4000 people has problems with blue and yellow. If you try to accommodate everyone, you just can't use color for information. I think using blue and yellow is a reasonable compromise.

White-on-black vs black-on-white should work, right? Though that would probably be less readable for other visual impairments.

Beyond what we traditionally think of as color blindness, there is an almost unlimited number of vision impairments your users may have that call for different colors, levels of contrast, and font size. To make software that is truly accessible to people with vision impairments, you need to make sure the user can create custom themes and that your software works well with screen readers.

There is none. The real answer is to always make the colours configurable. Red/green by default is fine.

Red-green color blindness affects 8% of males. Red/green by default can be annoying to the not insignificant amount of us who are affected.

You're just prompting the original question again.

Yellow is unreadable on a screen.

They used to make amber monitors alongside green ones. Yellow on white doesn't work, but why use a white background unless you're simulating paper?

I use both black on white and white on black. Usually, I find the latter enjoyable in the evening / night, but occasionally a bit depressing / oppressing during the day in my text editor. I guess it's also weird to have a bright room and a dark screen. But not in the terminal, where a black background always feels better for some reason.

So, why use a white background? Because it may feel better, and it may have nothing to do with paper.

Also, an objective reason: with black background in your text editor, it can be painful to switch to windows with a white background. If you try to set everything black background, you run into bugs: broken webpages, mails that set a white background anyway (bonus if they don't set the text color, or nothing is set but some words are highlighted or colored), documents, PDFs. I know because I tried. With support for dark themes in CSS it will probably improve but we are not there yet and you pretty much are in an unsupported territory.

The question also work in the opposite way: why use a dark background? Same answer: preference. For ecological reasons? It depends on the screen, and it should be measured especially if you compensate by setting the screen brightness higher.

I associate the diff colors with traffic lights: red means "after applying this commit, we STOP running this code..." and green means "...and we START running that code".

No value judgement intended, and who doesn't love to see a diff with a ton of red replaced with just a little green? Someone was cleaning house!

100%, I always tweak any color theme I use to have comments highly contrasting green or orange... dunno what's with the modern trend of making everything eyes-hurtingly-colourful, but then going and muting out the parts that should stand out the most.

Another pet peeve I have is why tf do all color themes try to color variable vs. functions vs. fields differently: they never get this right in dynamic languages, and they couldn't anyway bc variables often hold functions in them.

Basically all modern / editor-default color themes are dead wrong and annoying!

(VSCode and Visual Studio ones may be on point occasionally, but they fail at dynamic languages too and only end up spewing meaningless distracting colors everywhere.)

A few years back I decided to start a new colourscheme in Vim which I called “bland”. It started out with reverting all of the colour and term portions of syntax/syncolor.vim, and using black (#000) on white (#fff) (I had hitherto used a dark colourscheme, but decided to try a light one), with keywords bold, and that was it. After a week of that (a deliberately enforced delay), I succumbed to adding a little bit of text colouring, #cc0000 for strings, #009900 and italics for comments, and for no particularly good reason #0000cc for numbers. I added pale background colouring for diffs too. It’s grown a very little more complex since then, but not much. I haven’t ever switched back. I made a dark variant of it last year for the odd occasions where I want a dark colourscheme. Then it’s primarily white on black.

Most colourschemes out there are absurdly low-contrast. Part of my inspiration in finally getting round to making this colourscheme, and going for a light background, was experience several years earlier of using Vim on a not-too-bright laptop on a bus with substantial sunlight: I always had to switch to a dark-on-light colourscheme to be able to read the code at all.

Comments are necessary for a million reasons and the people who argue against them often haven't maintained someone else's code (or even their own).

A few: side effects, ordering that's required for correctness but not checkable by the language, guarding performance tricks from getting deleted.

An unfamiliar person trying to find out where in the codebase a thing happens relies on comments. Comments are much more readable and much more searchable than functions, in the same way that blogposts and comments add semantic terms to web documents to improve search.

Also intent -- to guide us in situations where 'this function is doing undesirable things but I have no idea what it's supposed to do so I can't fix it'.

Yes they get stale if not updated; it's a living spec. But most teams don't update any specs so code & comments are still the best one we have.

I agree about the diffs and have written the same thing myself. Deleting code is good! Adding code is neutral, at best. (You get a new feature, of course... but also new bugs!)

As for syntax highlighting, I'm not really sure what we want out of it. I like it for typo protection; type "cnost" and it doesn't turn blue, fix it to "const" and hey! pretty! It must be right. But it doesn't go far enough. If you call "foo.bar()", Github turns "bar" blue, regardless of whether or not it's possible to call "bar()" on "foo". My editor doesn't highlight those, but it should; if the method is callable, make it pretty, if it's some made up thing that isn't going to compile, make it ugly.

I think, at best, what we use syntax highlighting for is to break up what seems like a monotonous large quantity of text. Kind of like how I started a new paragraph to emphasize this point; it does help the reader. But I think we could do way way better, it's just that people seem to have given up. I think the excuse is along the lines of "it's too slow to use a 1970s era computer to figure out what methods are available"; that's true, but we are not using 1970s computers anymore. Why are compilers or syntax analyzers so slow, anyway? We can play real-time multiplayer games that render 240 snapshots of a 3D virtual world every second... but compiling hello world takes on the order of 200ms. Seems strange. No wonder our tools are so bad. What we're doing must be very hard for the computer.

(Github, however, has no excuse. They have all the time in the world to produce good syntax annotations; it's not like you're typing new code into that window. And their syntax highlighting does significantly worse than any editor I've ever seen.)

I don't really have the patience for armchair psychologists arguing about the meaning of colors in syntax highlighting anymore.

Red/green for deletion/insertion is less or more standard across tooling. It's not a quirk of GitHub and if you're going to make an argument about it shaping our value judgements about code contributions I'd like to see an actual paper or study please.

As others have pointed out, comments can have a lot of different reasons to exist. Inline documentation can be useful for tooling but should fade in the background when looking at the code directly. Commented out code generally should just be deleted but there are some rare circumstances where you might want to leave it.

Since we're already deeply in "unfounded personal opinions presented as fact" territory, I really prefer when important comments are explicitly marked using a standard keyword like "NOTE", "WARNING", "FIXME" or "TODO" because editors can be configured to highlight these lines differently, completely avoiding this flaming mess of an argument.

Every time an article about comments comes around I wonder: am I the only one who likes lots of comments, even those that don't add _any_ added reasoning, if they provide a clear visual distinction between things? The "Damn right it's ugly!" example from this article is infinitely more readable to me than his suggested replacement.

I agree with you. It's always easier to ignore comments than to not have them and trying to figure out stuff. I vastly prefer a 100 line function with comments every ten lines about what is to happen next to twenty, five line functions with "great" names (they never are), that are sprinkled about the whole file making the whole thing a case study in reinventing the goto statement. Though it often seems many people consider the later to be "better" and "self-documenting" code.

To be fair though, three line comments for every member seems a bit excessive to me as well.

> Perhaps it’s not as pretty, but it’s more usable. [Edit: quite a few people disagree. I suggest it would take some time to retrain your eye.]

Yikes. That's probably not the best way to approach improving usability - hectoring users that their interpretation is wrong.

Tonsky (Nikita Prokopov) view on syntax highlighting: https://www.youtube.com/watch?v=l1b7Da2DnPo&feature=youtu.be...

> quite a few people disagree. I suggest it would take some time to retrain your eye.

Or, the author is asserting that their approach is better without any real evidence other than their own line of reasoning. There's a great deal of arrogance in this post, like the assumption that red and green have universal connotations (just look at the chart emoji to see a counterexample). Do Japanese programmers have inherently better code because the existing red/green semantics in Japan match up with the author's argument? Probably not. It's an interesting couple of ideas but without meaningful data I wouldn't consider making these changes.

I often write comments before I write the code as it helps me think it out. Then I leave the comments there even when they are not necessarily highlighting critical points. Often I find them a useful reminder later on.

I don't think I've ever looked at some code and thought I wish there were less comments. I don't see why comments have such a lowly status. Of course you can tell when someone wrote a comment because they felt they HAD to...stuff like:

    /* Adding one to X */
    x = x + 1

Which I've actually seen...but anything even remotely intelligent is generally welcome, I think.

Honestly, I find those kind of comment more distracting than useful.

I once read somewhere that comments should explain the reason rather than the action. For example:

    /*
       x is taken from a system counter but it needs
       to be consumed by humans. So we add 1 because
       humans don't count from zero
    */
    x = x + 1

is a more useful comment.

Yeah I definitely agree with this. If I'm incrementing x in such a way that it's pretty clear what the meaning is (e.g. it's actually called like cur_page or something and I'm iterating over paginated data), then comments don't add a lot of value. Especially if they're not actually kept up to date with code changes.

On the other hand, comments like, "Hey don't change this because if you do, it'll break things in subtle and hard to test way because x," are definitely useful.

but pageCountDisplayed = pageCount + 1 is more useful still.

In that specific case, potentially - bare in mind it's imaginary code you're refactoring. There will be occasions when "ugly" code is required. The point of my post, which I suspect you missed, is that comments will generally be more useful if they describe the purpose of that code (which is harder to deduce) rather than what that code does (which often can be easily deduced just be reading the code).

The point of my post is that code will be more useful if it describes the purpose of that code. Sure, for the rest of the time there's comments.

Yes, I got that. As I said:

> In that specific case, potentially - bare in mind it's imaginary code you're refactoring. There will be occasions when "ugly" code is required.

ie, I don't disagree with your point however it's not always possible to refactor code for readability. Plus you're still missing the point that writing better comments can give you additional information ("why does it do it") that you might not gleam even from even well written code ("what does it do").

I think the whole situation with comments is a lot more nuanced than the author suggests. Namely, there aren't only the "important" and "redundant" type of comments[1], so the whole discussion about making them more visible or less visible is bound to be severely biased right from the start.

[1] The following (amazing) article discusses code comments at length:

http://antirez.com/news/124

Fading out comments is exactly right. This choice in syntax highlighting is correctly based on the observation of what the vast majority of comments are, not what some blogger thinks ideal comments should be.

Important "must read me" comments can be accommodated in syntax coloring via some additional notation:

   //
   // this is faded toward the background
   //
   // ! this is loud
   // ! read it!
   //

And, you know, unless I'm focusing on that area of the code for a specific reason, I probably don't want to read that. Should I need to turn my attention to that area of the code, I will read it, even if it is tastefully dimmed out.

One problem with a loudly colored comment is that there is no "marked read" button once you get the message, like in a message inbox. No matter how many times you read it, it stays lit up. (Maybe there should be such a feature. If a browser can remember what links you have visited, and show them in a darker color, a text editor could keep track of which loud comments you have already read.)

As others have pointed out, choice of colours does not neccessarily convey the message author insists on.

What's else, one could make a similar argument on the use of + (a good thing) and - (a bad thing) to say that removals should be marked with +, and additions with -. Maybe switch to sad and happy emoticons?

I am pushing it a bit just to make a point (because yes, + is even more commonly used to indicate addition, and - to indicate substraction or, well, removal). There is this whole science dedicated to making reading nicer, more efficient and more comfortable, and we want none of it.

I think there are better ways to make code more readable in our editors than changing a few colours.

Inspired by Knuth's literate programming renders of TeX and METAFONT source code, I've experimented with variable-width fonts for code (why are we programmers not allowed to read beautifully typeset text when everyone else is?), but editors today are not really comfortable with that.

Comments are both important and distracting.

I immediately prefer the faded comments because they are there if I want to read them. I'm not going to struggle to understand and reason about the comments.

I may well find myself needing to re-read and reason about the code that follows, so it's good that it's easier to follow the code without distraction.

It would be very easy for syntax highlighters to highlight things withing comments (e.g. if I write a "IMPORTANT: blah" in a comment, that is highlighted more than other comment text). There are editors that support this.

Emacs is among them.

Most of the JetBrains editors highly TODO in a bright color.

This is a very opinionated and I would say personal issue.

I also think most syntax schemes (the highlighter is perfectly fine, let us be technically correct) are very wrong for my own purposes.

This thing is the wrong colour, this looks like a candy party, some colours should be used only for such and such thing, strings should always be this colour, etc.

So, I made my own syntax colour scheme with my own conventions, and it is great.

But I don't try to convince anyone to use my colour scheme. That would be preposterous and intrusive.

Previous discussion (2014): https://news.ycombinator.com/item?id=7728781

I am currently reading Clean Code and there are so many useful hints in there, comments being one of the thi gs that stuck in my head. Talking about syntax highlighting, I edited my editor to treat @Todo and similar comment additions in the same way as errors: they do not belong thete and should be fixed as soon as possible. Marking them ass errors led to several small fixes. After reading this article I might try the same with regular comments.

Related: please never use red to give me feedback on what I typed into your form. It’s not dangerous if I have skipped filling out a field. And it’s awkward because it’s not clear at what point you should “warn” me about it; after all, the form usually starts out empty, and that’s not considered an error.

By focusing on what I completed you give a much more helpful vibe, and you can reserve red for destructive actions, like permanently deleting something.

I used to swear by syntax highlighting, but then I tried turning it off after hearing of someone else who tried and never went back.

That was five years ago. It felt weird for about ten seconds. These days I find code with syntax highlighting very noisy and almost impossible to deep read.

It's quite possible that it was always like this, but that I was numbed to the effects and lacked reference points.

Whatever the case, I don't miss it at all.

I strongly recommend trying a middle ground. I find nearly all highlighting schemes in use today overly garish, so I always find myself customising my own with relatively few colours with the idea of doing as little as possible to bring out the structure of the code:

- Comments and string literals can look like code without being code, so they get their own separate colours to make it easier to quickly scan past to where they end.

- Types live in a different dimension from the rest of the code, and tell me a lot about what it does, so they get a different colour.

And, finally, the one I've been trying for a while but am still not convinced about:

- Structural keywords (for loops, branches, etc.) get a separate colour as well.

All these colours are of course relatively neutral. I'm especially confused by people who use bright red for anything. That's a colour I use extremely sparsely for actual errors and bugs.

I also tried coding without syntax highlighting but it only lasted a few months.

One of the downsides is that when you show your code to other developers who don't have the necessary visual bandwidth, they get uncomfortable.

One of the few things syntax highlighting actually helps with is for catching typos in keywords. (To the trained eye, this could be replaced with just bolding or italicizing the keywords.)

Today I'm using "the colorful words" again (as non-technical associates have described syntax highlighted code), and still looking for a syntax highlighting theme which does not look like crap. (Gruvbox is the closest I've gotten yet.)

Giving each identifier its own color (e.g. https://medium.com/@evnbr/coding-in-color-3a6db2743a1e) is another interesting idea.

I think this raises an important issue; some comments are important and it would be helpful if they stood out as such. I disagree with the idea that since SOME comments are important, therefore, ALL comments should stand out. Others have pointed out how comments marked with TODO are treated differently by syntax highlighters. I’m going to start prefixing my important comments with NB (nota bene).

Thanks for pointing out that NB doesn't denote minor comments (as I believed), quite the opposite.

> multiple people have suggested a different interpretation: old code bad, new code good. However, since that would be a similarly invalid value judgment, the argument below is still valid

Well: if you regarded the removed code as better than what you're replacing it with, you wouldn't be committing these changes, right?

I wrote a minimalist Textmate theme based on the same thinking, namely that comments should stand out from the surrounding code. Check it out: https://github.com/KaptajnKold/Minimal

Comments are washed out because the compiler/interpreter will completely ignore them. That's what your syntax highlighter is trying to tell you - that these lines are unimportant because it they have literally no effect on the program.

Instead of using colors in diffs, why not change the typography? Make removed lines less visible, and added lines more visible, perhaps grey text for removed and bold black for added?

There is awesome plugin for VSCode, Better Comments. I disabled most of highlighting in syntax, rainbow brackets and better comments is more than enough

Note that vimdiff does use neutral colours by default.

I honestly don't see why discuss syntax hilighters. I mean, I like vim with green comments and red operators, over black bg, and my neighbour uses x-emacs with gray bg, no color coding but with some bold and italics. Why should we care about each other's formatting? We never had issues with looking at each other's screens. Btw, same goes for curly on the same line or the next.

I love this article. Nice re-framing of color choices.

This makes me think it would be nice to have at least two functionally distinct comment types: remarks (to be visually hilighted), and temporarily disabled code (to be visually suppressed). I suppose comment lines (remarks) and comment blocks (code) could be used for this, but as the author points out this would need to be a widely adopted convention.

This article is from 2015.

2014 even.

It's a comment, it may be obsolete.

TL;DR: OP doesn't like the colors used in common syntax highlighters.

And to that I say, change it. Editors these days are designed to make color-scheme changing as easy as possible.(I can confirm this about vim, emacs, sublime, Atom)

I've never understood this idea that comments are only necessary because the code is somehow flawed. This seems to be based on an ideal of beautiful code that both tells the computer step by step what to do and at the same time paints a bigger picture and expresses the intent of the programmer.

In reality though, code isn't poetry. C, Pascal, Javascript, etc. aren't meant to convey the thoughts of the programmer, but to give a machine clear instructions on what to do.

Humans aren't good at reading code. If we were, natural languages would have evolved like that, but they haven't. The idea of writing code for a machine and adding meta-information for humans to better understand the context isn't a bad idea, it's efficient.

What's more, when your code really does perfectly convey the intentions of the programmer and makes comments unnecessary, then your program is encoding information that the computer doesn't need, in a format that makes it harder for the computer to distinguish between relevant and irrelevant information.

Comments can convey hard-won information. Often developers will spend hours digging into an issue and then see a configuration or subtle change as the end result. That inocuous little bit of code is some of the most expensive, and brittle, code in the code base, but there is nothing to suggest it.

They might attempt to capture that knowledge in a git message, but that is destined to be burried in the sands of time.

Absolutely this. The time I find comments really valuable is when they remind me (or someone else) 18 months down the line that the other, obvious way to do this thing is subtly wrong, or when they justify using this particular value (perhaps with a link to some outside reference). Comments are mostly hints and metadata.

For example, in a recent file that deals with the database:

    // note: the ROW() constructor below is required in Postgres 10+ if we're updating a single column

(There was a syntax change from Postgres 9 that was caught by our tests)

    // these are the only meaningful values in Postgres: 
    // see https://www.postgresql.org/docs/11/sql-set-transaction.html

(Justifying why we don't support the whole SQL-standard range of transaction isolation types)

    // on trapping the following two rollback error codes, see:
    // https://www.postgresql.org/message-id/1368066680.60649.YahooMailNeo@web162902.mail.bf1.yahoo.com
    // this is also a good read:
    // https://www.enterprisedb.com/blog/serializable-postgresql-11-and-beyond

(An audit trail for why we catch some error codes but not others that initially look similar)

It takes time to "context up" on code you haven't read in a while (or ever). You have to read it, understand how the parts fit together, understand any gotchas and what purpose it serves for other modules.

All this takes time.

Comments are just a way of speeding up the process of "contexting up". Typically it's done by saving a bit of that mental context as a comment.

Ideally you want to save a piece of context that's easy to express, but took a long time to understand in the first place.

It seems like you haven't been exposed to spaghetti code with a million comments vs well designed modular code with few but useful comments. People don't just dream up that difference, it does often change other programmers' way of thinking about the code and helps convey intent far better than exhaustive comments.

It is true that people often take these ideals too blindly and their beautiful architecture brings little in comparison with simple obvious code. (I'm often a culprit there.)

The problem comes when people go from "good code needs few comments" to "never add comments to your code".

You're mixing up two orthogonal things. Your dichotomy is false, a straw man.

Code overspecifies. As long as there are programmers, the clearest code in the world should still have comments indicating intent. And comments won't save unclear code.

> Humans aren't good at reading code. If we were, natural languages would have evolved like that, but they haven't.

Give it some more time. I know it's far fetched, but chances are once human-computer interaction (HCI) is accessible for all humans and they transform into cyborgs (hybrid human and machine), code would be a more efficient means of communication as it is the perfect compromise between binary code (that pure machines understand) and natural languages (that pure humans understand).

As an HCI Researcher, I hope not...

The irony is that the historical branching of PL into VPL and then finally into HCI was all about getting away from code to interact with the computer.

Who's arguing that? OP is talking about how useless comments drown out the few truly important comments.

You can say how you wish comments were done, but in practice a section of code with a lot of comments tends to indicate unresolved complexity. The worst is when you can tell the original author used comments to indicate how they wished the code worked, but it doesn't. Sometimes the comments are from the next maintainer trying to figure out what the hell is going on because there is a bug in there somewhere.

The other problem with comments is multiple maintenance. It's very common for a change to be made to the code but not the comment. Now you've got lies misleading the next poor developer who dives in there.

Documentation comments can be useful, but I cringe when I see lots of comments per block or statement.

> Humans aren't good at reading code.

That's something you can get better at, but it requires discipline and effort. Programmers who have no intention of getting better at it think the comments will save them.

> That's something you can get better at, but it requires discipline and effort. Programmers who have no intention of getting better at it think the comments will save them.

Yeah. And people who make memory errors in C are just bad programmers. At some point people will have to accept that their preconceived notions are just that and not some mythical rule that others have to discover to find enlightenment.

I guess something requiring discipline and effort makes you defensive. You can't really think all programmers are equal. How do you think the good ones got better?

> That's something you can get better at, but it requires discipline and effort.

Find me one programmer who's as fluent in C as in any natural language.

If you think I said anything like that, then you're not as good at natural language as you think. Why would I defend an argument I didn't make?

As a developer I've gone through:

1. Commenting in the redundant way

2. Avoiding comments where possible

3. Using comments to convey intent in public APIs, and occasionally to explain how something works inline.

#3 came from working totally remote for a year.

We need to be very clear that the specific thing the author is objecting to is mandatory javadoc - the adding of comments which are just copies of the function name in English and convey no non-obvious information. These are definitely unnecessary for those reading the code. They should only be put in if there are consumers of the API who can only read the javadoc and function signatures, not the code.

(On my Visual Studio theme, comments are green on a dark grey background. What's the significance? Probably none.)

If JavaDoc comments are necessary for documentation but unnecessary for reading / editing the code, then perhaps the editor should deemphasize JavaDoc comments and emphasize normal comments.

I think the same should be true of type annotations. They are important to the compiler and as documentation, but should be deemphasized relative to the actual logic.

I found it surprising that the author didn't mention the possibility of deemphasizing doc comments at the same time that they increase the emphasis of regular comments. Doc comments have value for consumers of libraries, so I'm not always able to remove them, like the author did. However, doc comments have a slightly different syntax, so we can make regular comments prominent, like the author suggests, and we can make doc comments less prominent so they aren't distracting.

I find that adding the mandatory comments everywhere ensures that you won't forget to add that extra line of information when it does make sense. It's a good habit, like looking over your shoulder before switching lanes even when you know there's nobody there.

There are two sorts of comments - "What" comments and "Why" comments.

"What" comments tell you what the code is doing. In a lot of cases, depending on the language, the need for these can be reduced by writing clear code. This is much easier in, say, Python than Assembly. Even in Python though, sometimes you can be doing something a bit subtle where a 2 line comment can clear things up. These comments aren't irreplaceable because with a bit of reading and work, you have all the information to work out what is happening.

"Why" comments are much more important - telling the reader WHY the code is doing whatever it is that it's doing. The 'trim()' comment referenced in the article is a great example of a Why comment - all the reading around the code wouldn't give you an explanation (although sometimes git blame will).

Many 'what' comments are superfluous, almost no 'why' comments are - they are the collective memory of design decisions that otherwise lives in people's heads.

"all the reading around the code wouldn't give you an explanation (although sometimes git blame will)"

Right, as long as the commit messages talk about the 'why' instead of the 'what'. (e.g. 'Make it look bigger on mobile', instead of 'Add META tag with viewport and scaling')

True. I was mostly thinking of commit messages that say "Fix bug where we don't handle x" implying that this change is to handle X.

I've written some really complicated code that crossed layers (due to a third party embedded & unfixable system working against the spec) where each line had two to three comment lines explaining why the operation below was necessary.

Also, I'm not sure if calling Javadoc interface documentation "redundant" and "obese" is warranted. If it feels useless, it is not verbose enough.

Isn't your example a perfect case of the comments only being necessary because the code is somehow flawed?

From the comment, it sounds like the code is doing a reasonable thing dealing with a complex problem. The complexity of the problem deserves documentation.

Code being somehow flawed and reasonable are not mutually exclusive. It wasn't stated what the actual problem was the code was solving, so I can't say whether it was complex.

The code needed comments because it crossed layers – in general a sign of bad code. So the idea of "if your code needs comments, there's probably something wrong with it" definitely holds.

Sometimes you need not to do bad things to handle a bad situation (e.g. handling a third party embedded & unfixable system working against the spec), but that does not invalidate the fact that comments are an indicator of "somehow flawed code".

I understand what you are saying but personally I'd rather focus on understanding the codebase rather than on grading it. In this context, I often find comments very helpful, especially the "why" comments.

It had to cross layers, because the original implementation was flawed. The $vendor had designed the their protocol stack well, but implemented it against the very spec they wrote – for example, the outer protocol frame length field did not take into account character escape codes which were a property of the inner protocol. Instead of a protocol stack, the escaping has to be handled with a multi-layer state machine.

The vendor knows their protocol is buggy, because in their PC maintenance software they have arbitrarily chosen to start frame sequence numbering one higher than the escape character so that they can avoid triggering the bug in most cases. It still breaks down when the payload contains that prohibited escape code. Service techs are used to the whole thing randomly requiring retries and constantly joke about how repairing the $vendor's stuff has the best billable hours per work done ratio.

I assume given the rest of the context you were not implementing a FIX parser - but you’d find the same escape code layering violations if you were!

This strikes me as a good, but incomplete, taxonomy of comments.

What about comments that describe our assumptions? I guess that's a special-case of 'what' comments. Such comments are often better expressed as assertions in code (i.e. adding more code to improve readability, rather than reworking the code). Assertions have the considerable advantage that they don't go stale as the code is changed.

> although sometimes git blame will

That's a great point. Detailed commit messages are a good way to record the 'why' points. Unlike in-code comments, they don't bloat and dilute the source. Of course, they're also less immediate. (I guess I'm not sold on comment-folding as an answer to this.)

It's also a point in favour of fine-grain commits. If you squash your commits, 'git blame' becomes less able to help you track a line of code back to its original motivations.

Personally I would consider listing assumptions as a 'why' comment.

Knowing the assumptions gives the reader the context for why certain decisions were made, and why they may still be valid decisions or not.

Come to think of it, 'assumptions' is awfully broad. I was thinking of in-code assumptions (We assume x is non-negative), but I think you're thinking of requirements-level assumptions?

I agree that requirements-level assumptions (We assume the Vogon server will allow us to make at most 4 connections at any time) are exactly the sort of thing that should be captured in comments. I'm not sure there's a bright line between assumptions and requirements here, really.

My other point there was that any non-trivial code-level assumption that can reasonably be captured with an assert, should be captured with an assert, in preference over a comment.

If you’re assuming x is non-negative I would want to know why. Is it a function of what x represents in the real world? Is it something that we agreed on but there’s no physical reason x can’t be negative? Did the dev just assume x can’t be negative because it was easy and no one ever talked about it? And if the code looks like it assume x will never be negative but there are no comments explaining why then I’ll assume it just wasn’t thought about/discussed at all and know to be careful around this code.

That way when I go to update this code in the future I know if and why I have to worry about if x could be negative now.

Plenty of "what" comments are valuable. A whole lot of my code is prepended by a few paragraphs describing some algorithm from a paper and a link to the full thing. An outline of "this is what the whole thing end-to-end is doing" is fantastically useful.

>The idea of writing code for a machine and adding meta-information for humans to better understand the context isn't a bad idea, it's efficient.

It's a great idea. One of the best. I think many people will agree with that.

But there needs to be an equally effective way to keep the comments up to date. Because in my short experience programming professionally, the insidious part about comments is that as soon as one is shown to be a lie, none of them are reliable anymore. And it's very easy for a comment to become a lie as code evolves.

This is why things like unit tests are more attractive as a form of documentation - if the tests lie, the build fails, forcing you to fix lies.

This is my primary problem with comments. I have worked in very large 20year ol code bases both when I have been on the team for most of that time and when I walked in at the end. In both cases almost half the comments are at least partially incorrect.

I've worked on large, old codebases before, too, and in my experience half the functions are at least partially incorrect (i.e., have bugs), too.

The solution in both cases is the same: when you find problems, fix them. Don't throw out the baby with the bathwater.

Maybe I'm reading the wrong programs, but I haven't seen any unit tests that were an adequate replacement for either comments or out-of-band documentation.

For example, I looked up the SQLite source (which often comes up here as an example of a well-written program), picked the first source file I saw (alter.c), and one of the first comments is this:

    /* The principle used to locate the table name in the CREATE TRIGGER 
    ** statement is that the table name is the first token that is immediatedly
    ** preceded by either TK_ON or TK_DOT and immediatedly followed by one
    ** of TK_WHEN, TK_BEGIN or TK_FOR.

Another great one:

    ** Note that ON cannot be a database, table or column name, so
    ** there is no need to worry about syntax like 
    ** "CREATE TRIGGER ... ON ON.ON BEGIN ..." etc.

What unit test would you write to convey this information? Tests can be helpful but they serve a completely different purpose. You can of course write a test to cover the same ground as these comments (and knowing SQLite, they probably did), but a unit test to poke at corner cases is nowhere near as clear as simply stating what's going on.

I think the article means to suggest that one possible way to nudge programmers to keep comments up-to-date is to have editors that don't make them appear "washed out".

> But there needs to be an equally effective way to keep the comments up to date.

Yeah this is called code review. If someone repeatedly submits code with comments that are out of date then their manager needs to have a one on one with them.

Rust's doctests [1] are pretty useful for weaving some comments into the code while also allowing testing on compilation. If they are out of date, just running the test command will alert you that the code and documentation do not match.

[1] : https://doc.rust-lang.org/rustdoc/documentation-tests.html

I think it's motivated reasoning. People don't want to write them and it's difficult to put yourself in the mind of someone else and try to anticipate what issues they could have reading your code. You understand it, it seems obvious to you, therefor it doesn't need comments, which just so happen not to be enjoyable to write.

Reply on news.ycombinator.com