(2017 Week 20) Inline Comments Errata / Feedback
Closed, ResolvedPublic

Description

In 2017 Week 20, we've shipped a number of changes to inline comments in Differential and Diffusion.

Most of these changes were aimed at refactoring the code to support future feature development and fixing obscure bugs which most users are unlikely to encounter. Features should start landing in the coming week, and we'll do more of a "feature announcement" writeup in 2-3 weeks once this stuff feels stable. However, some visible things have already changed:

Persistent Header: While reviewing changes, there is a new persistent header which shows which file you're currently looking at (see D17957 for a screenshot). We originally had a similar header in 2012, but temporarily removed it for a brief period of 5 years. I currently intend to add more features to this header unless we get substantial feedback that it is loathed.

Scrollbar Annotations: A new element provides icon annotations near the scrollbar, showing where in the document changes and inlines are and allowing you to quickly jump to specific points of interest. The major goal goal of this change is to make it easer to keep track of things like this:

  • "Done" () vs "un-done" () inlines. If you like checking off every inline, you can now tell at a glance if you're missing any.
  • Comments from older versions of a change () vs comments on the current diff ().
  • Draft comments you've made () vs comments others have made.
  • Comments you're currently writing ().
  • Generally, to provide a better spatial UI for navigating changes.

This is currently fairly rough and may or may not stick. If you like it / hate it, feedback could help us figure out whether to keep it, change it, or get rid of it.

Multiple Edit/Undo: Previously, edit/undo state was global and you could not edit more than one comment at a time. Each comment can now be edited independently. This is good and bad (see below).

Hide vs Collapse: The "hide" behavior, which folded groups of comments completely into the sidebar, is now a less aggressive "collapse" behavior which reduces comments to a single line. I expect future changes connected to T8909 to add a way to completely hide things. This was largely aimed at fixing a lot of bugs which were hard to tackle with the old approach, and at making keyboard navigation more consistent and predictable.

Key Command Changes: Some changes have been made to keyboard commands:

  • r can now reply to changes, not just comments.
  • R can now reply to comments, quoting the comment.
  • w can now mark changes "done" (or remove the mark).
  • q can now toggle the visibility of changes.
  • Click-to-select: Clicking the header of an inline or the scrollbar annotation for that inline now selects it with the keyboard focus reticle. You can click again to deselect it.
  • The reticle should now do a better job of remembering your position in the document when you make edits.

Known / Suspected Issues

Undo Clutter: If you, e.g., create and then cancel a lot of inlines you can end up with a lot of "Undo" clutter. Previously, each "undo" wiped out existing undo state. I currently plan to make this use a rule more like the old rule (where you can only "undo" something until you take another action) unless we see feedback that multiple undo is great.

Forgetting About Half-Written Inlines: It is now easier to lose track of inlines because we allow multiple simultaneous edits. For example: start writing an inline, scroll somewhere to look at something, catch another issue, add a new inline there, forget about your old inline.

Previously, you would be prevented from starting the second edit, which would remind you that you were doing something else. Now, the second edit will work independently, so you might more often forget about the first edit.

My hope is that the added flexibility is worth the increased opportunity for errors.

Part of the goal of the new scrollbar annotations is also to help with this, by providing a visual cue that makes it more difficult to forget that you have unfinished inlines.

Documentation: Some of this stuff could use documentation and blog coverage, but I expect to write that after completing T8909 + T8250 in 2-3 weeks.

Design Stuff: I don't think any of this looks too awful today, but design is evolving / nonfinal. See T12688 for some stuff we may look at.

Highlighting Rules: The rules around when lines are highlighted have changed a little. For example, lines are no longer persistently highlighted when editing a comment.

One reason for this is that it's now possible to edit multiple comments simultaneously, but there's currently only one highlighting reticle.

I believe the current behaviors are basically fine, although I liked some of the old behaviors slightly more. If multi-edit sticks, I may try to make the new behaviors a little more similar to the old behaviors. If we get rid of multi-edit, I'd likely make things very similar to the old behaviors.

Mouse "Prev" () and "Next" () Actions Removed: Previously, each inline had mouse navigation actions to jump to the previous or next inline. These have been removed. Rationale is: I believe they may be very rarely used, and removing them gives us more space to pursue changes like T11401 in the future.

You can perform a similar navigation action by clicking the inline comment's header to select it, then pressing n or p. You can also select it by clicking the scrollbar annotation (if prototypes are enabled), or just use the scrollbar annotations to navigate.

(You can also use n, p, N, P, j, k, J and K to navigate changes more broadly with the keyboard, and can take more actions without using the mouse.)


Feedback

We're open to feedback in these areas particularly:

  • How do you like the persistent header element?
  • How do you like the scrollbar annotation element?
  • Is the greater editing/undo flexibility a net benefit (more power) or net loss (too easy to lose track of things / end up with a lot of clutter)?
  • Do keyboard commands work better now? How does clicking inlines to select them feel?
  • Anything that looks/feels like a bug.

Details

Commits
D18274 / rPc217d7619c5f: Make "A" hide or show all inline comments
D18262 / rP0d8f4170f4dc: Fix an issue when deleting the entire content of an unsubmitted inline comment
D18129 / rP9b93697d52f4: Move "List Inline Comments" to the inline header dropdown menu
D18128 / rPb3b30dde6ac9: Add options for hidding inlines to the Differential header banner
D18127 / rP3be36783b377: Consider inline comments with draft checkmarks as "unsubmitted"
D18126 / rP887bd2d66ef0: In the UI, rename "Hide Inline" to "Collapse Inline"
D18103 / rP8692d673c8ab: Fix minor inline comment header button behaviors
D18070 / rP48c6ca40c44f: Add an "Unsaved" button to the Differential persistent header
D18065 / rPd42d69aef699: Clean up some PHUI/PHUIX button behaviors
D18051 / rP683647f1fb90: Add PHUIXButtonView and a UIExample
D18045 / rP83e99fb691aa: Add a class to the Differential banner when unsubmitted/unsaved changes are…
D18044 / rPcc0a6fd3aa45: Remove the ability to leave multi-line inline comments on touchscreen devices
D18043 / rPd20221dc7d82: Remove Differential "objectives" UI
D17982 / rP4d2c7e4d3d5d: (stable) Show the curent selected inline in the objective list
D17981 / rPe6843b1c00f3: (stable) Show "reply" inlines as replies in the objective list
D17978 / rP87a4940924bc: (stable) Fix a diff objective issue where objectives could appear in the wrong…
D17980 / rP253f7b0bb9bd: (stable) Show a snippet when hovering inlines in the objective list
D17979 / rPaabb791c174b: (stable) When a user cancels a new inline, clear it from the objective list
D17977 / rP429a0ce4e699: (stable) Make Differential objective markers show a brighter "editing" state
D17974 / rP1495c80e62ea: (stable) Hide the Differential scroll objective list on trackpad systems
D17975 / rP1bccdd69cb92: (stable) Stop long filenames in objective list tooltips from being cut off
D17982 / rP7d44e7cb4d2f: Show the curent selected inline in the objective list
D17981 / rPe15009b76e1b: Show "reply" inlines as replies in the objective list
D17980 / rP4dff754502bd: Show a snippet when hovering inlines in the objective list
D17979 / rP7a40dd380ee7: When a user cancels a new inline, clear it from the objective list
D17978 / rPc056ff56cc95: Fix a diff objective issue where objectives could appear in the wrong place
D17977 / rPaf07600aaac7: Make Differential objective markers show a brighter "editing" state
D17975 / rP8b2a06387dbc: Stop long filenames in objective list tooltips from being cut off
D17974 / rPaba209e9990f: Hide the Differential scroll objective list on trackpad systems
D17976 / rPab80d3ef0c62: (stable) For the diff banner, detect the current changeset better
D17976 / rP6945e80feed5: For the diff banner, detect the current changeset better
There are a very large number of changes, so older changes are hidden. Show Older Changes
  • The persistent header should now select more intuitive changesets.
  • The scrollbar annotation is now disabled for trackpad "aesthetic" scrollbars (like the 0-width scrollbar on OSX if you don't have a mouse connected to your laptop). If we retain the element, I plan to enable it eventually, it just requires us to move content around and generally make a larger change.
  • The scrollbar annotation is now disabled unless phabricator.show-prototypes is enabled.
  • The scrollbar annotation should generally work better and be more useful now.
  • I've deployed these changes to this host.
epriestley updated the task description. (Show Details)May 21 2017, 12:40 PM
20after4 added a subscriber: 20after4.

Synthetic comments (made by lint) are currently shown in the sidebar annotation with a pencil ( ) icon.

This is misleading. Instead, I'm inclined to not show them.

On mobile I very quickly get an inline comment box when scrolling which then takes focus so scrolling is aborted.

I'm left-handed, so I easily hit the (relatively wide) gutter with my thumb.

This does not happen on our local install that has not been updated with these changes yet, only here.

epriestley added a comment.EditedMay 23 2017, 12:06 PM

This is an intentional change to address T1026 (allowing inline ranges to be added via touchscreen devices). Previously, it wasn't possible to comment on a range of lines on, e.g., an iPhone/iPad.

Now that we listen for this drag event, we can't distinguish between "you pressed the screen on a line number, intending to scroll" and "you pressed the screen on a line number, intending to begin leaving an inline comment". I think we also can't make the decision after the fact, and have to freeze the screen right away by killing the touchstart if we're going to interpret it as an inline.

Some possible approaches:

  • You could reach over the inline line numbers toward the middle of the screen to scroll with your thumb. This may not be comfortable or practical, but maybe it's acceptable given that the behavior has a reason for existing.
  • We could revert the behavior, and not support comments on a range on devices.
  • We could use the old behavior (no ranges) on small devices (phones) and the new behavior (drag to select a range) on medium devices (tablets). I don't like this much because it seems like a lot of complexity.
  • We could try to guess if a particular touchstart intends to scroll or comment. The only signal we could use for this that I can come up with offhand is the time since your last scroll: if you scrolled recently, assume you want to keep scrolling. I don't like this much because I think it's likely to feel flimsy/inconsistent to the user and be hard to predict/understand.
  • We could give users an option to disable this behavior. I don't like this much for the reasons in T8227.
  • We could give users a "left-handed" accessibility affordance option which retains the behavior, but moves the line numbers to the right on devices. I don't like this much because of T8227 / general complexity.
  • We could change the behavior to "tap to begin a range + tap to end a range". I think this is possibly a better way to set a range on devices, but it makes the far more common action (comment on only a single line) twice as difficult. I think this makes discovering the behavior of the interaction a lot more difficult, too.
  • We could change the behavior to "tap and hold to begin a range + drag". I'm not sure we can actually do this, and it would be almost impossible to discover.
  • We could introduce some novel UI mode like a "scroll lock" button somewhere in the UI. When you pressed this button, the screen would lock and allow drag interactions. This is weird and clumsy.
  • We could change the behavior to "tap to begin a range + drag right to extend it downward". Although I think this would likely be very difficult to discover, I don't particularly hate this. It preserves the simple behavior and preserves normal vertical scrolling. This is still fairly clumsy, though.

If you'd still prefer the old behavior after understanding why the behavior changed, my inclination is to revert the behavior and decline to support comments on line ranges from touchscreens, at least for now. I don't think this feature has much value or utility given that single-line comments are available anyway.

Broadly, essentially no one develops software on a device, and no IDE I'm aware of is touting mobile support as a killer feature, nor does anyone believe that typing code on your phone is the next big thing in engineering. I think software engineering will continue to look a lot like "typing code" for a long time, and will mostly continue to be performed with a physical keyboard. There are some mixed-mode devices which act like both a tablet and a laptop, and maybe these will bend the rules a bit, but I'm fairly confident that the nexus device for software development will continue to have non-touchscreen input -- and a fairly large, high-resolution screen -- for the foreseeable future.

As such, I think it's reasonable to expect Differential to serve a more shallow role on small devices, more akin to "keeping abreast of changes" than "performing detailed review", and reasonable to not try to support every review feature on mobile, since these devices are secondary/support devices until everyone gets really excited about coding on the go using their thumbs, a virtual keyboard, and a tiny screen.

I understand why the behavior has changed, and I'm not particularly opposed to keeping it as-is. I can easily reach over the line number - it's just that it initially appeared as a regression so I had to note it here.

As such, I think it's reasonable to expect Differential to serve a more shallow role on small devices, more akin to "keeping abreast of changes" than "performing detailed review", and reasonable to not try to support every review feature on mobile, since these devices are secondary/support devices until everyone gets really excited about coding on the go using their thumbs, a virtual keyboard, and a tiny screen.

Definitely. I mostly keep up with changes on my phone while traveling, but it bare ever (if at all) happens that I actually review properly.

chad added a subscriber: chad.May 23 2017, 1:39 PM

I'd be fine removing the range select on mobile.

As such, I think it's reasonable to expect Differential to serve a more shallow role on small devices, more akin to "keeping abreast of changes" than "performing detailed review", and reasonable to not try to support every review feature on mobile, since these devices are secondary/support devices until everyone gets really excited about coding on the go using their thumbs, a virtual keyboard, and a tiny screen.

There are small devices and then there are 12" tablets with a keyboard. I've done lots of detailed review on such a device and, barring the possibility that I'm a uniquely unique person, I think it's not indefensible to there support everything you can do on a desktop browser.

Like in T10229, I think the qualification to determine the right amount of mobile simplification and intentional loss of features shouldn't be "is this a mobile device" but rather "how large is the browser".

In the case of scrolling, neither a left nor a right handed person could accidentally touch the line numbers in a 2up diff layout. (Unless they have some seriously alien hands and an predilection to scroll in the middle of the screen.)

It does add some amount of complexity to do one thing for touches on a small screen and another on a larger screen, but I think it could be argued that any amount of responsive design is complexity and we still do it because we like mobile. And in this case, I'd say it's not necessarily even about mobile: there are laptops with touch screens and desktops too for that matter.

So in the choice between removing touch support for multi-line comments altogether or just removing it from the 1up narrow screen view, I'd like the latter.

Unless they have some seriously alien hands and an predilection to scroll in the middle of the screen

You can leave comments on the left hand side of a 2-up view -- that is, scrolling in EITHER of these areas on 2-up would trigger the problem:

So I think this is still potentially "all left-handed users who use high-resolution tablets", not just three-handed users who scroll with their middle hand.

I think that when I personally use a tablet, I often either hold it in my left hand and use a free-floating pointer finger on my right hand to interact, or place it on a surface and hover over it with a partially open right hand to interact. In both modes, my interacting hand is not anchored to the right side of the tablet. I believe I middle-scroll with some frequency. I'm not certain that I'd trigger this interaction by mistake, but I don't think it's completely outside of the realm of possibility as a (mostly normal?) right-handed user.

barring the possibility that I'm a uniquely unique person

I don't think you're uniquely unique, but I think "users who use tablets + keyboards to do detailed review" may be heavily outnumbered by "users who use tablets with their left hand" and "users who hover their hands over tablets and 'flick' / middle scroll".

I think there's also a major difference in degree-of-badness here: when we choose the "comment" behavior and get it wrong, the middle-handed user feels like we arbitrarily broke scrolling for no apparent reason (above, for example, it sounds like @richardvanvelzen already understood the rationale but reported this as a "regression", not a preference for the old behavior). When we choose "scroll" and get it wrong, the Surface Pro (or whatever) user can see that the interaction is doing the normal thing they'd expect it to do in every other case. This can still be frustrating, but I think it's usually much less frustrating than breaking scroll.


Actually, maybe another relevant question is: have you used this new code yourself (as it currently exists in HEAD) for any significant amount of time, and found that it actually represents an improvement (specifically, that it really never interrupts scrolling actions in your setup/environment)?


Like in T10229, I think the qualification to determine the right amount of mobile simplification and intentional loss of features shouldn't be "is this a mobile device" but rather "how large is the browser".

This is tangential, but I think this is the opposite of what we did in T10229. That is, we added code to test "is this a touch screen device?", rather than relying on "how large is the browser?" to determine behavior.

An equivalent change here might be, e.g., detecting that you have a physical keyboard and enabling the behavior. But:

  • I don't think we can do this reliably.
  • Even if there was a way to do it reliably, I'm not sure the additional complexity is worthwhile.
isfs added a subscriber: isfs.May 29 2017, 3:33 PM

We could change the behavior to "tap and hold to begin a range + drag".

I think this would make sense. It may be difficult to discover, but perhaps not too much: i would naturally try tapping and holding to access additional options if a simple click didn't achieve what I wanted; if I saw the line highlight after doing this, rather than a menu appearing, I would naturally try dragging. Given range commenting is a feature that is a candidate for removal if it doesn't play nicely with scroll, IMHO, this option would be better than removal.

I rarely review on my phone, but it is convenient to know it works, as occasionally I will get a request while travelling and if I can quickly log in and leave a comment or two, it's helpful. I could do without range comments in this scenario, of course, but being able to make them would be better.

You can leave comments on the left hand side of a 2-up view -- that is, scrolling in EITHER of these areas on 2-up would trigger the problem:

Good point.

This is tangential, but I think this is the opposite of what we did in T10229. That is, we added code to test "is this a touch screen device?", rather than relying on "how large is the browser?" to determine behavior.

Yep. I misremembered that task. And in as far as it applies to this issue at hand, I think "is this a touch event" is the right thing to consider when figuring out what to do in general.

I think there's also a major difference in degree-of-badness here: ... less frustrating than breaking scroll.

I think the opposite argument could be made as well.

If the middle-handed user is unable to scroll by touching this area, their problem can be resolved by touching some other area. "Comment" behaviour causes resolvable inconvenience.

But the opposite isn't true: if the behaviour is to always scroll the Ambulatory Code Reviewer has no option short of finding an emergency laptop. "Scroll" behaviour causes irresolvable inconvenience.

Of course it can be argued that range comments isn't a critical feature. I do know I have missed it a few times working on my tablet but it didn't stop me from doing my work (if with slightly less elegance and precision).

In T12733#225442, @isfs wrote:

We could change the behavior to "tap and hold to begin a range + drag".

I think this would make sense. It may be difficult to discover, but perhaps not too much: i would naturally try tapping and holding to access additional options if a simple click didn't achieve what I wanted; if I saw the line highlight after doing this, rather than a menu appearing, I would naturally try dragging.

Actually come to think of it, isn't this already how text selection works in iOS? If you tap and move your finger you scroll. To "select" you tap and hold for a moment until selection begins and then you drag.

So maybe this option would actually be natural and easy-ish to discover after all.

Not sure it can be implemented easily though. If we handle touch down I guess scrolling is immediately inhibited by the browser. So maybe we can't add a timer and then decide later not to inhibit? Maybe just listening for text selection would work.

chad added a comment.Jun 7 2017, 3:18 PM

Clicking "Cancel" after starting an inline comment leaves "0/1 Comments" in header. (do you want tasks or comments for these issues?)

Comments are fine.

chad added a comment.Jun 8 2017, 1:01 AM

On D18102 I see other people's unsaved comments, I think. I also expect 0/2 to only be visible to the whoever can mark stuff done. Otherwise maybe just 2 or nothing?

"3 Unsubmitted" is the three synthetic lint about "TODO"s in the code (see T12806).

I can do either behavior for the "0/2" button if you want to pick whichever you prefer.

chad added a comment.EditedJun 8 2017, 1:09 AM

I probably should spend more time thinking about this UI, or maybe I should have taken more notes when I designed it.

Offhand, I think the x/y Comments is only useful to the author and they've marked one inline done. That is, it's to keep track of submitted and unsubmitted dones. If nothing has been marked done, it's not useful for anything else. So just to float this out, don't show at all unless you're the author and 1 inline is marked as done (submitted or not).

If you haven't checked anything and are the author (i.e., today, button is visible and says "0 / 2"), clicking it takes you to the first inline. That's at least a plausibly useful behavior?

If you're a reviewer and the button says "5/7", clicking it lets you jump to comments the author has not yet addressed. That might inform your review decision: perhaps you want to make sure the remaining unaddressed inlines are minor feedback and not major concerns before you "Accept".

I don't really know what this button is for or why we have it but it's not inherently obvious to me that the current behavior is un-useful.

I can implement the behavior you propose, though:

  • Button is never visible for non-authors.
  • The button becomes visible for the author after at least one inline is in the "Checked, Unpublished" or "Checked, Published" state.
chad added a comment.EditedJun 8 2017, 1:25 AM

I could go either way. At least 0/2 feels bad since it then gives the impression we think you should be marking stuff done. Let's just kill the 0/2 case. Only show / if 1 is marked done and see how that feels. I can clean up the UI before cut too.

I think my initial plan was this would only show up basically if you were into marking stuff as done. If not, it never exists and you use Differential as before.

chad added a comment.Jun 8 2017, 1:28 AM

Is there a pre-cursor to D17955 I should read up on? Or was T8250 the main impetus?

The objectives UI wasn't solving any specific problem or really motivated by any particular request, I largely just wanted to try it out and see if it made it a little easier to navigate diffs in general. I think at least some of the feedback in the vein of T8250 is roughly "it's hard to see the big picture when changes have a lot of comments", and it seemed worth trying to see if we could make the big picture a little more clear without splitting the UI apart completely. Some (most?) IDEs have similar features, where either things like functions/classes, or lint warnings, or compile errors, are marked in the scrollbar or a small view of the file is shown:

I think these features just serve as a sort of general map of the code that lets you see a high-level overview and find points of interest more easily than a plain scrollbar can: you can see where problems are, get a rough idea of how many there are, jump around to particular locations easily, etc. It doesn't tell you "there are 17 errors", but it can show you "there are about a dozen errors or so" and "most of the problems are grouped into two places" at a glance, and it's more spatial than "17 errors", which I tend to find useful personally.

The closest direct motivation was T8250, yeah -- I generally think T8250 isn't going to produce a very useful UI (at least for me) -- and basically still don't understand the problem it's solving, except in terms of mitigating "reviewers left 90 spelling corrections" nonsense -- so I wanted to see if there were other approaches we could maybe take to tackle the issue (or, at least, stimulate discussion which might get to the heart of it) without having to build what's probably going to be a totally separate "list of comments" UI. In an ideal world, half the users interested in T8250 would say "oh, now that I can see the little icons things feel more manageable, I don't really need a separate dedicated comment list anymore" and just leave the "90 spelling corrections" use cases which we could more easily dismiss or try to redirect into something like arc fix-every-comment-one-by-one or T10038 or whatever.

chad added a comment.EditedJun 12 2017, 6:11 PM

In D18112 I've marked 3 items as done (unsubmitted), but the header bar is still white, my expectation is it turns yellow.

alexmv added a subscriber: alexmv.Jun 16 2017, 8:37 PM

This might not be totally related but

  1. I really love being able to see the filename while scrolling through files
  2. It would be useful to have something similar to Diffusion's File Search on a Differential revision, to quickly jump to files based on name. The f sidebar helps a little but it's organized in a file-system layout which means the folder location needs to be known.

I think I found a minor bug. If I'm fairly confident that I want to remove my draft inline comment I'll EditDelete TextSave rather than just Trash - I think just so I don't end up with that yellow box that asks if I want to Undo.

  1. Create an inline comment
  2. Save the comment (no text content)
  3. The inline comment goes away
  4. The top-bar will continue to indicate that there's 1 Unsaved Comment

(I can reproduce on this install)

That's supposed to leave an "Undo" bar, still want us to fix the bug?

Removing the text and re-saving the inline comment is supposed to enable an Undo? Hmm..

(Oh, no, I'm mistaken.)

Well, I'm half mistaken. What you're seeing is a bug.

Saving an empty comment which previously had content is also supposed to produce an "Undo" row, but that's currently TODO'd and might not return as a feature.

I'm going to fix the bug (phantom "Unsaved Comment") for now without restoring the "Undo" behavior.

isfs added a comment.Jul 21 2017, 11:41 PM

+1 for not adding undo behaviour. I too avoid yellow undo bars by saving empty comments. Alternatively, I guess, you could put a "Permanently delete" link in the undo bar so with one extra click you could whisk it away (which actually would be easier than going through the edit, empty, save dance).

Is there opportunity for a hotkey to hide/show all inline comments? Or since it's accessible from the topbar is the intent not to add hotkeys?

If it's a toggle, what do you expect us to do if you press it with some inlines hidden and others visible?

Toggle each individual comment's visibility to the opposite but only if it's not for the current diff~

j/k

The scenario I was in while asking, a diff that's been noisy with comments and then gets an update and wanting to toggle all comments off while looking at the latest changes. Being an action from the top-bar now works great, I just leapt to thinking about hotkeys.

Maybe I'll put it on A, I guess ("Toggle All"), so it's sort of near q, which is similar (collapse/expand).

epriestley closed this task as Resolved.Aug 15 2017, 5:53 PM
epriestley claimed this task.

This seems to have calmed down.