Design Draft: Code Hinting

Article by: Garth Braithwaite

Design Draft: Code Hinting

First Design Draft

I personally couldn’t be happier with the open process the team is using to develop Brackets. Following their lead I will be doing my best to keep the design process as open as is useful by posting design drafts for new or planned features here on the blog. If you have any feedback on these design proposals feel free to respond in the comments, ping me on twitter, or find me in the Brackets IRC channel (garthdb).

Code Hinting

Currently the Brackets team is implementing an initial version of code hinting. This post outlines user experience design in connection with this feature.

Code hinting, at its most basic, is a mechanism for displaying and quickly completing code while the user is typing. The three main goals, in order of importance, for code hinting are:

1. Speed

The most important goal of code hinting is to help developers minimize repetitious typing.

2. Accuracy

By leveraging auto complete the developer should also be able to reduce the number of typos.

3. Education

Code hinting can also display options the developer did not know were available to them. This feature could be extended to give more information to the developer and further this goal; see Extension UI Guidelines below.

Basic UI and Interaction

The basic visual interface for code hinting consists of a list of available or intelligent complete strings depending on the partial string typed. In the example above the code hinting list consists of HTML elements that begin with the letter d.

As the developer types, the code hinting list will appear below the cursor, lining up with the beginning of the string being typed. Code hinting is passively called and will appear whenever the developer has typed something that matches the criteria for one or more list items. It can also be actively called using the keyboard shortcut (ctrl+ space or command+space) and will display results depending on the position of the cursor.

A list item can be selected using the mouse or up/down arrows and the enter key. Selecting an item will replace the partial string typed with the selected string.

The list is unobtrusive and hides when: the list is empty; the user hits esc; the string is completed; or focus is removed from the editor.

Specific Implementation

What the actual list of elements consists of depends on the type of code being used as they vary significantly.

HTML

Within HTML code hinting could be used for elements (tag names) and properties

Elements

HTML Elements could be implemented a few different ways:

Previously Used Elements

The most basic implementation would only show a list of elements previously used. The upside is that the list is always relevant to the developer’s habits. The downside is that the user will not see other elements available to them.

All Elements

The alternative is to show a list of all HTML elements based on the doctype of the file. This would avoid the downsides of the previous option, but would require that the list be up to date with the changing list of valid HTML elements.

Hybrid List

My recommendation would be to use a hybrid of the two. Show a separated list with the most used elements shown first, and any other elements meeting the criteria below.

Properties and Values

Properties and values would follow a similar pattern as the tag names themselves. Content within a tag should not trigger/use code hinting.

There are a few special property values that use project specific values.

Classes and IDs

Class and ID values would be code hinted with a list of classes and IDs used in project css files

External Files

The value for external source properties (such as src in the img element or href properties) code hinting would display a list of files in the project that would be valid, or directories that contain valid files.

In the example above, the code hinting list shows a list of directories that contain images, and images. If a directory was selected, the code hinting list would change to show valid files in that directory.

CSS

Selectors

Similar to class and ID property values in HTML, CSS selector code hinting would contain a list of classes and IDs used in the project. Element selectors would also be hinted using the same list as the HTML element code hinting.

Properties

CSS properties would have a similar code hinting solution to HTML elements, using either a list of previously used properties, an exhaustive list of all valid properties, or a hybrid of the two.

Values

Since CSS values are often repeated within a document or project, code hinting would use a list of previously used values corresponding to the property being defined.

JS

Because of the syntax used in JS, there wouldn’t be a separation between variables and functions in code hinting lists. Though they would be distinguishable by the parenthesis. See images below.

Variables

Functions

Other Languages

It would be difficult to have a code editor that could handle code hinting for all web languages out of the box. Extensions could help fill this void.

Extension UI Guidelines

Like all of Brackets, code hinting is meant to be extended. Below are a few ideas for adding additional information to the component

Icons

List elements could have an image or icon placed at the beginning or end of the element. In the above example the Chrome icon indicates that the details element is only fully supported by Chrome at this time.

Documentation

The code hinting list could also contain a details portion. In this example the area on the right of the code hinting dialog displays relevant details about the currently highlighted element. This would allow developers to learn more about the tags while they are in the context of the editor.

Conclusion

I appreciate you taking the time to review this design draft. When building a development tool that will be used day in, day out, the user experience is just as critical as the underlying features. If you have any feedback or ideas, please comment here or start up a discussion on our mailing list. I’ve also posted the source artwork on Dribbble.

The first code hinting story just landed in master yesterday (July 12, 2012) and is now ready for testing. It will make its official premiere in the Sprint 11 build. Because we believe in building small features, then iterating, only HTML tag hinting support is available at first. In the next sprint we will add HTML attribute and value hinting with CSS and JavaScript to follow later.

Note: This design draft is merely a proposal and does not necessarily dictate the final implementation of the feature.

Leave a Reply

Your email address will not be published. Required fields are marked *