Ruby In Steel 1

Back to -Tutorials -Sapphire (Ruby In Steel) Tutorials -Archives -Ruby In Steel 1

Ruby Code - Organizing, Annotating, Navigating

Some tips on tools to clarify your code

Ruby In Steel Developer has numerous tools to help you keep your code neat, clear and organized. These include everything from code folding on named regions to Task Lists for maintaining file-based and project-wide ‘TODO’ items. Here are a few ideas of things you can do to organize, annotate and navigate your Ruby and Rails projects...

TODO Lists - just one of Ruby In Steel Developer’s code navigation tools

Task Lists

Ruby In Steel Developer 1.4 introduced automatically updated TODO lists. When you enter comments starting with #TODO into your Ruby files these are automatically added to the Comments pane of the Visual Studio Task List (select View/Task List). Comments are not case or punctuation sensitive so # toDo... will work just as well as #TODO.

By default TODO comments are added to the Task List for all files that have been opened in the editor. Double-click a TODO item to go straight to the matching line in the code. If you want to view all TODOs throughout an entire project you can do so by selecting Ruby/Refresh TODO list. Note, however, that selecting this option will cause every file in your project to be searched and analysed; in large projects, it may take several minutes to complete.

You can also add Project-wide tasks to the Task List. These are tasks and reminders which are not associated with a specific line of code. Select the User Tasks pane in the Task List then click the Create User Task button to the right of the User Tasks combo box. This creates a new row into which you can enter a task. When the task is complete, click the checkbox that precedes it. The task will then be shown with a line through it.

Add User Tasks and check them off when they are completed

Double-click the left-hand column to set a priority

Hint: To sort your TODO items and tasks, you can click the column headers.

Searching

In addition to searching the current file, you may also search all the files in a project. Amongst other things, this gives you a simple way of locating ‘custom comments’ such as #DELETE:. Matched search items are displayed in the ‘Find results’ window. Double-click one of the results to go to the source code.

Double-click search results to go to the code

Bookmarks

You may place bookmarks on selected lines by clicking the Bookmark button in the Text Editor toolbar (or by pressing the associated hotkey - the default is CTRL+B, T). You may then navigate between the bookmarks in one or many files in your project by clicking the Previous and Next Bookmark buttons or you may restrict searches to the current file by using the Previous and Next in Current Document bookmark buttons. Another button on the Toolbar lets you clear all bookmarks.

Use the Bookmark toolbar to set and navigate bookmarks

You may also add bookmarks to the Task List. Select ‘Add Task List Shortcut’ from the Edit, Bookmarks menu or use a hotkey (default is CTRL+E, T:

Shortcut positions are indicated in the editor by a blue arrow in the left-hand margin

Go To

When you want to find the declaration of a Ruby class, variable, constant or method, select its name in your code, then right-click and pick the Go To Definition item:

Go To Definition is just a mouse-click away

When Ruby code exists for that item your cursor will be placed on its definition. If no Ruby code exists (if the definition was written in C and compiled into the Ruby standard library), the cursor will be placed in a dummy ‘pseudo-Ruby’ method along with explanatory documentation extracted from the C source code.

The Ruby Explorer

For a more visual way of navigating your code, use the Ruby Explorer (Ruby, Ruby Explorer). This shows an alphabetical list of classes, methods and variables both of the standard library and user-written code (custom classes are shown beneath the ‘Object’ branch). Click a class name to open a branch and view its methods. Double-click a method name to go to its code (or documentation if no Ruby code exists):

The Ruby Explorer

Navigation Bars

To navigate code in the current file, use the drop-down Navigation Bars over the editor. The list on the left navigates to classes and modules. The list on the right navigates to methods, constants and variables:

The Navigation Bars let you find things fast in the active source code file

The Document Outline

For a structured view of the current document, use the Document Outline (View, Other Windows, Document Outline or the hotkey which defaults to CTRL+W, U). This outline shows information on classes, objects and members in Ruby code, HTML and CSS structure or Embedded Ruby structure when working with Rails ERb templates:

The Document Outline of a Ruby file...

...and of a Rails ERb template...

...and here is the outline of the HTML ‘composite’ view of a Rails page-design (assembled using the Visual Rails Workbench)

Named Regions

In addition to code-folding based on Ruby syntax (you can collapse the code of classes, modules, methods, while..end blocks, for..in loops and many other types of construct), you may also create arbitrary ‘named regions’ that can be collapsed out of sight when you want to concentrate on other areas of your code. To create a named region just add a pair of #region...#endregion comments. A name after the opening comment is optional - for example #region User Interface Code:

Here I’ve added a named region (shown expanded)

This region has been collapsed out of sight by clicking the +/- marker in the margin - as you can verify by checking the line numbers

These are just a few of Ruby In Steel’s code organizing, searching and annotating tools. Be sure to read the manual (supplied in the software’s Zip archive) for information on other features such as bracket and keyword-matching, outline expansion options, the various ‘Synchronize’ options to exclude selected types of files and folders from the Solution Explorer and (for Rails developers) Ruby In Steel’s dedicated code-and-design environment, The Visual Rails Workbench.

© SapphireSteel Software 2014