4

NOTE: This question explores methods for increasing for a target user group.

Background: Readability is invaluable when dealing with large amounts of text. For some users, programmers, that text represents "objects" in a computer system. These objects often have a hierarchical structure (i.e. objects have parent-child and sibling relationships with other objects). Traditionally, these "nesting" relationships have been communicated to the user by increasing the left margin to show which object belongs to which (the child object is indented greater than its parent, and siblings start at the same level as each other).

The Problem: On one hand deeply nested code is hard to read. On the other hand, visualising nesting levels are necessary to understand code. De-nesting code/html requires a lot of effort, which only improves readability, not actual code effectiveness, accuracy etc.

Is there a way to communicate hierarchy other than adjusting indentation?

I will provide a small piece of sample text, along with my first attempt at making it more readable using some colors, shapes, etc. I'm sure someone can do a better job. Let's make a breakthrough together!

Normal nesting using white-space (text version):

Normal nesting using white-space

Attempt 1: show nesting in margin:

show nesting in margin

attempt 2: add shapes in code to show level:

add shapes in code to show level

attempt 3: replace filled overlay with bordered area markers: replace filled overlay with bordered area markers

  • 6
    readability does not have much to do with User Experience? The user is a programmer in this case. – Harry Mexican Apr 30 '18 at 7:56
  • 1
    I think this is a question for stack overflow as apposed to here. – UIO Apr 30 '18 at 9:43
  • 3
    If it was implementation oriented he'd be asking how to do the indenting in the code, not tips on which method works best for the user – mgraham Apr 30 '18 at 10:54
  • 4
    This question was closed on the software engineering stack exchange because it was deemed to be a 'UX concern, not a software engineering question'. I will let you guys think about the senselessness of hearing the opposite objection here. :) – Harry Mexican May 1 '18 at 21:27
  • 3
    This is absolutely a UX question. @HarryMexican, perhaps if you just provide a link to your code sample hosted on Git Gist or similar, people might not so reflexively vote to close without reading your actual issue. – maxathousand May 4 '18 at 20:31
5
+100

"The Problem: On one hand deeply nested code is hard to read. On the other hand, visualising nesting levels are necessary to understand code. De-nesting code/html requires a lot of effort, which only improves readability, not actual code effectiveness, accuracy etc."

1st thing: Do you know that 'de-nesting' improves readability for sure i.e. you or others have done a test which shows the indenting causes a problem rather than just understanding a program being actually hard? It may be generally easier to read text if aligned nicely but programs are a different kettle of fish - the code isn't necessarily sequential for one - there's conditions, callbacks etc which mean the code structure plays as much a part as sequence.

Program code is usually displayed as an indented tree (using white space) to show the nesting level of the structure, as in the first method you show. By attempting to replace the white-space with a colour coding, you're attempting to replace the most powerful perceptual cue for quantitative information (position, in this case the horizontal component) with a colour coding cue which is generally accepted as being more useful for non-quantitative data (i.e. categorical data). You've implicitly accepted that fact in your next 2 solutions by having the colour coded bars in the margin indented anyways even when the code is fully left aligned

Have a look at this past work to see if what you're doing is actually a good idea:

Program indentation and comprehensibility Authors: Richard J. Miara Univ. of Maryland, College Park Joyce A. Musselman Univ. of Maryland, College Park Juan A. Navarro Univ. of Maryland, College Park Ben Shneiderman Univ. of Maryland, College Park

http://doi.acm.org/10.1145/182.358437

Their findings were:

Two styles of indentation were used--blocked and nonblocked--in addition to four possible levels of indentation (0, 2, 4, 6 spaces). Both experienced and novice subjects were used. Although the blocking style made no difference, the level of indentation had a significant effect on program comprehension. (2--4 spaces had the highest mean score for program comprehension.) We recommend that a moderate level of indentation be used to increase program comprehension and user satisfaction.

Most rated zero indentation to be poor. It's a old paper sure, but there's not much better/newer out there

  • I'm going to accept your answer because you've taken the time to think through the problem and even looked up some research on the matter. That being said I disagree with your POV on most of the points you've mentioned. Not enough space here to go over all of it, but indentation is universally agreed to make reading code less pleasurable, at the very least, if not less effective. That's why people prefer promises to callbacks. There's even terminology for it, like callback-hell, etc. I appreciate your thoughts and apologise for whomever downvoted you. – Harry Mexican May 1 '18 at 21:23
  • Thanks for the upvote H, but none of it's my personal opinion or POV, I'm just pointing out other people's empirical evaluations on the subject. Code indentation doesn't make code unreadable or difficult, rather difficult & complicated structures in program code are reflected via code indentation. See this paper for a study that used indentation to accurately measure code complexity --> doi.org/10.1109/ICPC.2008.13 - removing the indentation doesn't make the code less complex / more readable, it just removes an efficient cue for signalling that complexity to the user – mgraham May 2 '18 at 10:09
  • I'm arguing that there could be a more efficient cue for signalling complexity than code indentation, because in my personal experience, and those of other coders, heavy indentation does make code harder to read even after taking into account code complexity. I stated an example above. Promises reduce the nesting level that Callbacks add in asynchronous code. The two approaches have identical code complexity, as they are identical to a compiler, but one is easier to parse for a human because of reduced nesting. – Harry Mexican May 5 '18 at 16:19
  • "but one is easier to parse for a human because of reduced nesting." - and again the nesting/complexity is then reflected in the indentation. I've not found any experiments that show removing indentation improves readability - some really early papers say indentation makes no difference (a couple reffed in this paper - doi.org/10.1145/78607.78611 ) - in which case there's no point trying to show it using another visual variable. Bear in mind the nesting you're showing is essentially a tree structure - and indentation is one of the most common ways to do that. – mgraham May 7 '18 at 15:25
  • PS. If you are interested in alternatives to indentation for hierarchies, have a look at this treevis.net . However, imo (this time :-) ) none of them work better than indentation with program code / text. You really are going to have to come up with something stunning to best Donald Knuth – mgraham May 7 '18 at 15:39
2

As a person who's studying programming, I don't think it's a broadly applicable problem, but rather a problem affecting a subset of use-cases.

For example, object-oriented languages (Java, Kotlin, C++, etc.) lend themselves to splitting code up into atomic functions, so if you have very deeply nested elements, you just need to restructure your code (and you'll be better for it).

Now, with some markup languages like XML, you have a point.

Just remember, any solution you have will only suit specific use-cases. In OOP, encouraging less nesting is a feature, not a bug.

As for alternative ways of showing hierarchy, off the top of my head:

  • Typography. There's lots of things you can do with type. Think headings in standard documents. You can change the size, tweak the color and opacity, change the case, and play with different font weights. Aside from color and opacity, I don't think any other indicators would work well, but it never hurts to try.
  • Spacing. You may use different margins for different hierarchy levels.
  • Enclosure. E.g. use lines and shapes to delineate sections.
  • Interaction. Play with interactivity. Interaction can make deeply nested code more usable, without removing indentation as a cue. One frequently used pattern are collapsible sections, but you don't have to stop there. Any of the other hierarchy indicators listed here can be made interactive. For example:
    • Color. The active line and its children could maintain its color, while the rest turns dim gray.
    • Spacing. The active section could be separated with vertical margins.
  • Separate areas. This ties in with interactivity. You could show hierarchy using columns, with the first column being the top level, the second column being its children, and on and on. You could show children on a separate page, in a dialog, or an expandable section.

Lastly, I recommend reading more about Gestalt psychology. It deals with how we mentally group items.

  • +1 A pretty comprehensive list of variables that you can play with when it comes to visual styling, but it is hard to tell which combinations will work the best when it comes to creating the most readable hierarchy. – Michael Lai May 5 '18 at 23:39
1

If this was simply text on a page then the normal conventions of varying the font size and spacing between lines of text would be more than sufficient to deal with the level of hierarchy and structure (although you could certainly try to apply some of it as well). However, in this instance it is not necessarily true that the content at the top of the hierarchy is more important compared to the content nested deeper (e.g. just wraps everything up).

Lets use the examples you have provided and see how they can be improved to illustrate what is important when visualizing content in hierarchy.

Normal whitespace

The problem here is that the only hierarchy represented by the whitespace is the depth of the nesting and not the hierarchy of the page, which still needs to be interpreted by going through each line and understanding the structure, and also it becomes more difficult to distinguish the hierarchy as more levels of nesting is introduced into the code. Clearly there are more dimensions to visualize then there are ways to represent them, so you need to introduce more elements.

Show nesting in margin

The use of the vertical bars to represent code at the same level of hierarchy is a way to address the problem of just using white space, and adding colours helps to make the different levels even more distinguishable. However, this is still a solution that cannot be scaled easily when you have too many deeply nested layers, and still only solves the problems of helping people identify the depth of the nesting but not the semantics of the hierarchy.

Shapes and border markers

Not really sure that it adds much more value to what has already been done with the bars in the margin, and in fact this is probably an example of overloading the visual representation so that it actually increases the amount of visual information that you have to process without too much additional benefit. If you compare it to the previous solutions you'll find that it is easier to process the hierarchy information without having to look at the code compared to having the colours, shapes and borders mixed in with the code.

An alternative

Use the vertical bars in the margin to show the hierarchy because I think it is the most minimal way to represent hierarchy. I like the idea of colour coding the blocks of code (both in the vertical bars and the shape/border) but you should match it with the type of HTML element and not the hierarchy because then you lose the ability to encode two different types of information at the same time. In the example you showed two elements at different hierarchy coded in different colours when they could be the same colour but having different depth of the vertical bar to show that they are the same element at different hierarchy.

Actually, I have seen HTML editor (or text editors in general) that allow you to expand and collapse nested code when the syntax of the content is specified. These editors allow you to also expand and collapse the code at specified levels of hierarchy and is therefore a much more efficient way of accessing the content (i.e. they allow you to navigate the hierarchy instead of only visualizing it).

The suggestion of opacity by Tin Man is quite interesting, as it offers a way to show the depth of nesting combined with focusing the users attention to the area that they are interested in. But rather than a fixed visual cue, you could introduce some interaction to make this relative to the level of hierarchy you are currently at, so that as you move down the hierarchy you decrease the opacity of the levels below.

  • interesting idea to match part of the visuals to the html element (in the case of html) instead of the nesting level. Might play around with it in an gfx editor to see what it looks like. – Harry Mexican May 7 '18 at 6:55
  • @HarryMexican I think some of the more complex text editors allow you to customize the styling a bit more, but not sure how much more. – Michael Lai May 7 '18 at 22:13
1

One option is to use the "collapse" and "expand" ability for code blocks. Something like this enter image description here

  • code collapsing does actually provide some benefits, but require quite a lot of fiddling/input from the User. I've thought about whether an automated folding mechanism could partially solve the issue i'm addressing in my question. – Harry Mexican May 7 '18 at 6:53
  • @HarryMexican there are text editors that provide more specific options when it comes to expanding and collapsing the different levels, pretty sure sublime text editor or notepad++ would have default settings or plugins that would offer these options. – Michael Lai May 7 '18 at 22:14
1

Illustrating code hierarchy by using the left margin is common because it is effective1, though I sympathize with your view that it can become tedious to work with. Thus, I think the issue we should try and solve is not illustrating hierarchy in some other way, but rather provide tools that make navigating this code less tedious.

Visual Studio provides an option for the user to view a preview of their code as they hover over the scroll bar. This preview automatically shifts the code to provide the most effective "fit" for the hovered region.

Horizontal auto-scroll

You could incorporate this same auto-fit mechanic which will automatically reduce the left-margin based on what content is currently visible in the editor.

Alternatively, you could allow the user to link this behavior to a hotkey + click action that will automatically adjust the horizontal scroll bar to situate the beginning of the selected line to the left edge of your editor.

For example, if you configured this shortcut with Shift + click:

    <div>
        <ul class="list">
            <li> <!-- Shift-click here -->
                 Hello World
            </li>
        </ul>
    </div>

Scrollbar position:
[<][=====]                                     [>]

clicking on the <li> line would auto-scroll your window to show

class="list">
<li> <!-- Shift-click here -->
    Hello World
</li>
>

Scrollbar position:
[<]      [=====]                               [>]

1 Source: Personal opinion/experience.

  • Honestly, shift+click is very bad choice. Reserved for text selection for ages. – Frantisek Kossuth May 11 '18 at 15:13
  • @FrantisekKossuth You're right, but that wasn't really my point. – maxathousand May 11 '18 at 15:15

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.