Last week, JetBrains released RubyMine 6.0. The most significant feature is multi-project support; perfect for component-based Rails architectures. However, in this post, we’ll look at OS X keyboard shortcuts for some of the other new features.
At Pivotal Labs we have a basic policy for meetings, No Laptops Allowed.
At first this seemed harsh to me, and for business- inefficient. Within my first three weeks though, I’ve been converted. I’ve learned that the benefits of this rule are felt by team members and clients alike.
We all know that the multi-function, connected devices we love are distracting. Personally, I hate missing something important someone said during a meeting because I was reading an email or researching what I thought was a crucial factoid. Would that have happened if I didn’t have my laptop or smartphone out?
It seems the easiest way to avoid this feeling and encourage 100% engagement is to remove distractions. Few things can draw someone’s attention away as quickly as their email or the internet.
During meetings, it is important that everyone stays engaged. That way, everyone can share their perspectives on risks and opportunities for minimizing them. When someone is paying attention, they can alert the team of something they know of that can help or hurt the project if not addressed.
Beyond that, at Pivotal we emphasize that meetings are about teams and healthy communication. Meetings center on the team working together. When my laptop was open in my first few meetings, it was seen as disruptive to team dynamics. I had put up a barrier which prevented my integration into the team.
I like many of you thought that I was using my laptop to take notes and therefore it was ok. But, because no one could tell that notes were the only thing I was typing, it became distracting to others. Additionally, one of the visiting clients took my laptop’s presence as an invitation to bring his computer in as well. This meant that a crucial team member ended up responding to emails and surfing the web, when his attention needed to be in the meeting.
After a meeting, one of the Pivots on my team came over to offer me some feedback about this. She reminded me that each conference room has tons of index cards, pens, and markers for everyone to write notes. In today’s modern age, it’s amazing what the old fashioned pen and paper can do.
Before I sign off on my first blog post, I want to emphasize that there are reasons (even at Pivotal) where a laptop is welcome at a meeting. These reasons generally include when the laptop is used as the source for a projection the team is looking at together and as a way for a remote team member to dial in. When in use, we try to turn off distracting notifications to keep focus on the meeting.
Try out some laptop free meetings where you work and tell me how it goes…
Like most engineers, I do a lot of optimizing, often just for fun. When walking to work I seek the shortest route. When folding my laundry I minimize the number of moves. And at work, of course, I optimize all day long alongside all my engineering colleagues.
Optimization, by definition, requires an objective function as the basis for measuring improvement or regression. How short is the route? How many moves does it take to fold a shirt? But what is the objective function at work around which my team and I should optimize?
I’ve worked in many software engineering organizations where the objective function is an unstated confusion that evolved on its own over time. It’s often a bit of “don’t break things” mixed with a dose of “conform to the standards”. Sometimes more destructive objectives find their way into the culture: “get yourself seen,” or worse “don’t get noticed.” And my least favorite, “horde your knowledge.”
Recently, while working with a client, I had to state my views on a good objective function for a software engineering team. It’s To predictably deliver a continuous flow of quality results while minimizing dark time — the time between when a feature is locked down for development and when a customer starts using it.
Predictable: Your process has to be stable and sustainable. It’s not about sprinting to collapse; nor is it about quick wins followed by a slog through technical debt. It’s about a steady pace over a long time. Hence the volatility measure in Pivotal Tracker; a good team has low volatility, and therefore their rate of delivery is highly predictable.
Delivery: Code is not worth anything until it is in use by customers. Calling delivery anything else often leads to spinning wheels and wasted effort.
Continuous flow: Activities that potentially disrupt the flow and would be better off if dealt with in the moment, in the normal run of things. For example, I find mandatory code reviews disruptive and demoralizing. Gatekeepering steps like these, by definition, stop the normal flow and send things back for rework. In contrast, pair programming often achieves the same quality and consistency objectives in real time and without disrupting the flow
Quality: This is a relative measure. The work needs to be done sufficiently to avoid rework (i.e. bugs) and to prevent the accumulation of technical debt. Spending more time trying to achieve “quality” beyond these measures is just waste.
Results: What it’s all about.
Minimizing dark time: Many software engineering organizations miss this one because it’s driven by the business rather than the needs and craftsmanship of the engineers themselves. And yet, minimizing dark time is perhaps the most critical contribution that an engineering team can make to a business.
Dark time is what the business experiences between when the engineers remove the businesses ability to re-spec a bit of work and when they hand back a working result. In this dark time the business can no longer refine their decision nor observe and learn from the results. They’ve ordered (and paid for) the new car, but are waiting for the keys. It’s dark because during this stage there is nothing for the business to do, with respect to that feature, but wait.
While coding I experience the same dark time when working on a slow code base or, worse yet, working with a slow test suite. My TDD cycle grinds to a crawl as I wait a minute or more (the horror!) between when I hand my code to the compiler/interpreter and when it spits back the red-green results.
If you hate twiddling your thumbs waiting for slow tests to run, think how frustrating it is for the business folks when their engineering team throws them into the dark for days, perhaps even weeks. Of course they pipeline their work and find ways to be useful, but the dark time still sucks.
When a software engineering team chops dark time down from a month to a week business folks cheer. When the engineers chop dark time down to a day or less, the business folks do what us coders do when working with a fast test suite… we fly.
As a business, design is built around deliverables: clients pay for wireframes, mockups, prototypes. As a practice, these deliverables are a means to a single end: communicating design decisions. The Agile Manifesto prefers “Working software over comprehensive documentation”, so why are designers spending time on artifacts the user will never see? Agile seeks to minimize waste, so taken to its logical extreme, all documentation is waste. That doesn’t mean documentation can (or should) be done away with entirely; it’s necessary for teams to function (particularly at scale). But it does suggest that minimizing documentation is a Good Thing, and that designers ought to be seeking to communicate design decisions with the least amount of work possible. Welcome to the Minimum Viable (Design) Deliverable.
We are uncovering better ways of designing experiences by doing it and helping others do it.
Through this work we have come to value design decisions as the fundamental unit of work for designers. We prefer to communicate design decisions by:
- Comments over Wireframes,
- Wireframes over Low-Res Mocks,
- Low-Res Mocks over High-Res Mocks,
- A Few DRY High-Res Mocks, Supported by a Live Styleguide, over Exhaustive High-Res Documentation
That is, while there is value in the items on the right, we value the items on the left more.
Using the Minimum Viable Deliverable
It’s easy! All you need to do is 1) socialize the idea that “less artifact can be better” among your team, and 2) always ask the question: what’s the least amount of deliverable that we need right now? Is a high-resolution mockup really the only way to communicate that design decision? Could we get away with describing the design decision in a sentence, and then using the saved time to work through other design decisions? Or to implement some of the design? Making this question a regular part of your design process can greatly speed up your team’s Think-Make-Check loop, reduce the amount of high-resolution drudge-work, and make more time for the fun part: digging into design problems—and solutions.
By selectively hiding and showing sections of code, code folding allows you to focus on what’s relevant, while ignoring irrelevant details. Code folding is also a useful way for quickly getting a high-level overview of a large section of code. RubyMine adds custom folds to the standard list of editor code folding features. Custom folds can be used to effectively outline a section of code. In this post, we’ll look at code folding in RubyMine on OS X.
Folding Individual Code Blocks
A code folding toggle icon appears in the left gutter next to blocks of code that can be folded. Press
command + - and
command + + to fold and unfold foldable blocks.
Folding All Code Blocks
Fold and unfold an entire file’s code blocks with
command + shift + - and
command + shift + +.
After folding all the code blocks in a file, successively unfolding with
command + + will unfold to your cursor.
If a section of code does not have a folding toggle icon in the gutter, select it, then fold it with
command + ..
A folded selection appears as an ellipsis. Unfold it with
command + . or
command + +.
Custom Folding Regions
A custom folding region can be used to describe or outline a section of code. RubyMine uses a special Ruby comment for custom folding regions.
To create a custom folding region, first select the section of code, then press
command + option + T and choose “<editor-fold…> Comments” or “region…endregion Comments” from the “Surround With” dialog.
Finally, provide a description for the custom folding region.
You’ll have to manually create this comment if RubyMine doesn’t give you either comment option in the “Surround With” dialog.
Navigating By Custom Folding Regions
Navigate to a custom folding region with
command + option + ..
RubyMine can be configured to automatically fold certain code constructs, e.g., methods. To set these preferences, search for “code folding” in the settings dialog,
command + ,.
Don’t Forget About the Details
Not every developer is a fan of code folding. Folds are often used to hide long, ugly, or complicated sections of code. Once hidden, the code rots; out of sight, out of mind. On the other hand, hiding code behind folds keeps you focused, preventing unnecessary refactoring tangents. Like any technique, code folding has its pros and cons, try it out and see if it works for you.
RubyMine’s powerful “Go to file” command allows you to quickly jump to a particular file in a project. This is a great way to get started, but a development session often ends up being confined to a small set of files and directories. It’s inefficient to constantly search project-wide. Instead, use RubyMine’s convenient inline navigation bar to find nearby files. In this post, we’ll take a look at it on OS X.
Navigation Bar Basics
Open the navigation bar with
command + Up.
Navigate the navigation bar with the arrow keys or
control + N and
control + P. If you know the name of the file or directory you’re looking for, start typing it to find it via search.
This search bar supports many of the same fuzzy search features available in “Go to file”,
command + shift + O.
The navigation bar can also be permanently docked. Use “Find Action”,
command + shift + A, then search for “Navigation Bar”.
File management commands available in the Project tool window also work in the navigation bar.
command + N– create a new file or directory
F5– copy a file or directory
shift + F5– clone a file or directory
F6– move a file or directory
shift + F6– rename a file or directory
delete– delete a file or directory
Performing these commands from the inline navigation bar minimizes context switching. It also avoids wasting screen space on the Project tool window.
Preview files from the navigation bar with “Quick Definition”,
option + spacebar.
Development of a particular feature or bug fix is often localized to a set of code and test files. An effective strategy is to find a known initial file with “Go to file”,
command + shift + O, then work with and manage nearby related files and directories with the navigation bar. The navigation bar becomes a sort of local “Go to file” command.
RubyMine includes several commands to quickly perform common tasks, such as converting a Hash from Ruby 1.8 to 1.9 syntax, or viewing an object’s documentation without leaving the current file. These powerful commands eliminate tedious editing and context switching. In this post, we’ll explore them on OS X.
A lightbulb icon indicates intentions are available for the current line. View them with
alt/option + enter.
Quick Documentation Lookup
View documentation inline with
shift + F1 to view it in an external web browser.
If the docs are no help, press
alt/option + space to view the definition inline.
This is a useful way to check if something is defined.
Quick Evaluate Expression
During a debugging session, inspect an object inline with
command + alt/option + F8.
Quick Switch Scheme
Switch the color scheme, code style scheme, keymap, or look and feel with
control + `
Simple But Powerful
RubyMine’s “quick” commands showcase the power of an IDE. Intentions/quick fixes was the feature that convinced me to dive deeper into RubyMine. Viewing information inline saves time, and avoids losing focus. Once integrated into your workflow, “quick” commands will become some of your most used commands.
Adopting the convention of writing notes in Markdown has been hugely helpful for me. It’s an easy-to-use, easy-to-read, easy-to-learn, format for something I do every day, and a great example of convention over configuration. It helps to capture notes and events in high fidelity, at low cost. I can listen to a conversation and write almost automatically without having to think about how to structure my notes. I don’t have to decode my notes for other readers. It Just Works.
What is Markdown?
Markdown is a lightweight markup language…allowing people “to write using an easy-to-read, easy-to-write plain text format…then convert it to structurally valid XHTML (or HTML)…Markdown is a formatting syntax for text that can be read by humans and can be easily converted to HTML.
The syntax is pretty straightforward, and though it’s fairly deep, there’re a few major bits that I use all the time. Learn these two tricks and you’ll be 80% of the way to never having to re-invent your note-taking structure again:
The Two Main Tricks
At bare minimum, most documents have structure and content. To delineate the two, you’ll need some notion of a header. In a newspaper, examples of what HTML calls “headers” might be Headlines (“MEN WALK ON MOON”) and Subheadlines (“Astronauts Land on Plain; Collect Rocks, Plant Flag”).
Markdown has a few ways to describe headers, but I prefer “hash marks” or octothorpes. One hash for an H1, two hashes for an H2, etc.
# MEN WALK ON MOON ## Astronauts Land on Plain; Collect Rocks, Plant Flag
In HTML we might describe the top-level headline as an “H1”, the subhead as an “H2”, and we can go on from there, e.g. an “H3” (“Voice from Moon: Eagle Has Landed” and “A Powdery Surface is Closely Exposed”).
I find a use for headings on almost every document: certainly to title them, and occasionally to subtitle them. Any text-editor that is aware of markdown syntax can usually give an outline view with a single keystroke, which is very useful when editing and structuring thoughts.
HTML has a menagerie of lists: ordered lists, unordered lists, definition lists…the list goes on. (Actually, that’s about the end of it). Markdown lists are pretty intuitive, and (probably because I’m often recording a meeting or making to-do lists) I find myself using them all the time.
To make an unordered list in Markdown, prepend every list item with a hyphen.
To make an ordered list in Markdown, which I do far less frequently, prepend every list item with a number.
Ok, I lied, there’re three basic things. Here’s the last one. HTML has a paragraph tag, but in Markdown, to write a paragraph…you just type.
That’s it. Easy, right? This is why Markdown is so powerful: you really don’t have to remember much, but adopting a default convention means there’s one less thing to think about.
Headers and Lists will get you 80% of the way to making your notes understandable, but there’re a number of other fairly common markups I often apply to text.
- Emphases: surround text with
* single asterisks *to make them italic, or
** double asterisks **to make them bold.
- Citations: use an
> angle bracketwhen you quote text:
Houston, Monday, July 21—Men have landed and walked on the moon. Two Americans, astronauts of Apollo 11, steered their fragile four-legged lunar module safely and smoothly to the historic landing yesterday at 4:17:40 P.M., Eastern daylight time. (The New York Times)
- Links: Surround the
[link text]with brackets, and then follow with the link reference in
[All the news that's fit to print](http://nytimes.com). There’re actually a few smart ways to do this; it’s worth digging in and investigating.
- Self-Linked URLs: if you’re linking to a URL, you can just put it in
- Images: a bang, alt text in brackets, and then the path to the file, e.g.
![Man walks on Moon](moon.gif). This is actually something I do fairly rarely, and only in the final stages of writing and editing, mostly because thinking about code paths and where I’m storing the image usually gets in the way of recording or writing.
- Code blocks: put code blocks inside
`backticks`(or indent with four spaces).
There’s a lot more syntax to dig into; find it at http://daringfireball.net/projects/markdown/syntax.
Convention over configuration might be the biggest win in choosing Markdown as a default. There’s little need to pick a new structure every time you take notes. Another big benefit of Markdown is that it works in plaintext, which means its future proof. When Microsoft Word Home Office Supreme 2016 breaks all your old
.doc files, plaintext will still be alive and kicking. In fact, you can use Markdown for handwritten documents; I use it all the time to take notes on index cards. There’s another benefit: when I need to transcribe those Markdown index cards, I don’t need to guess whether I was trying to write in bold or whether my pen was leaking. Better yet, transcription becomes incredibly easy: I can transcribe without processing or editing on the first pass, and then review my work, process, edit, and do all sorts of other writerly things. This doesn’t sound that impressive, but I’ve found it to be a huge time-saver.
In addition to the straightforward benefits of using Markdown as a default, I’ve also evolved a number of hacks:
- Use hyphens for lists, asterisks for todos: because Markdown supports a few different bullet characters, I’ve started to assign them semantic meaning. Being able to quickly scan a document and see what I need to follow up on is pretty great.
- Markdown is platform independent! I use it for notes on index cards. This is a great social hack. I can look you in the eye while we chat and write on cards or in a notebook; try doing that on a phone or tablet.
- I’ve been experimenting with photo capture: scanning batches of cards into a card-friendly scanner (I’m using a Neat scanner these days; it’s ok), then pushing them to Dropbox (it syncs to my phone!) and I’m starting to experiment with Evernote in order to group cards (“Blog Ideas”, “To-dos”), though I’m pretty frightened by the proprietary Evernote card format.
- Translating notes (e.g. getting a team together to capture an experience report of a project) into presentation decks is really streamlined if you write in Markdown and then move to Markdown-based presentation tools like MDpress, Showoff, or Keydown.
So that’s the How and Why of my Markdown habits. Do you use Markdown? Do you have a system for notes? Let’s hear about it in the comments!
After opening a file, your next step is usually to search within that file for some text, or perhaps, a particular method. Like text editors, RubyMine supports simple text search. However, it also offers more powerful method and usage search. In this post, we’ll look at various ways to search within a file in RubyMine on OS X.
command + F to search for text within the current file. Use
command + G and
command + shift + G to move forward and backward through the search results.
After selecting text, search for it with
command + F.
After beginning a text search with
command + F, press
control + H to view recent searches.
Repeat the last text search by not entering a query into the search bar, and then pressing
Enable quick word searching by adding a shortcut for the “Find Word at Caret” command. I map it to
control + F3. If you use this mapping, then you may have to disable the OS X “Move focus to the the dock” shortcut.
command + F12 to view the structure of the current file in a popup, then type the name of the method you’re looking for.
This is quicker and more accurate than using text search.
Find usages in the current file of the symbol under caret (e.g., a variable, method, or class) with
command + F7. Use
command + G and
command + shift + G to move forward and backward through the usages.
Highlight usages in the current file of the symbol under caret with
command + shift + F7. Use
command + G and
command + shift + G to move forward and backward through the usages.
Esc to clear the highlighting.
Search for Code Not Text
By being aware of code, an IDE can allow you to search for a method, instead of performing a text search such as “def show”. Text search will always have its time and place, but use it as a last resort. Move on from old text editor habits and learn your IDE’s more powerful alternatives.
During development, it’s common to view and edit the same group of related files, to navigate the same classes, and to run and rerun the same tests. An IDE that keeps track of recent activities can help simplify performing these types of repetitive development tasks. In this post, we’ll look at how to view and re-execute recent activities in RubyMine on OS X.
So you have a team of four developers and a product manager. You seem to be in a good place: you’re using Pivotal Tracker to keep visibility into your backlog of work, your velocity is high and, more importantly, constant. Releases went well and the team you’ve built can efficiently mutate your software to suit every new product idea. It’s a proven recipe for success!
But now you have some more money and want to go faster. You decide that you need to grow the team. You add two more pairs in the hope of getting twice as much done.
Two months down the line, you realise things aren’t going quite as fast as predicted. Developers are treading on each other’s toes and build time is rapidly increasing because lots of slow high-level (or even slow unit-level) tests are being added. You need a solution to these problems, and you decide to mitigate developer work clashes and accidental double-work by carving the backlog into ‘tracks’. Instead of developers working on stories as they go, by picking them off the top of the backlog, work is allocated according to clearly defined areas of the system that you believe are separate enough to avoid people bumping into each other.
These techniques seem to solve the immediate problems you’re facing. It’s another winning formula, so you add another two pairs, bringing you up to six. Now you can really rip through features!
New problems arise. Now the build is really slow, and developers choose to run subsections of the test suite before a check-in. Long periods of red builds result. The incremental stories are feeding this problem: one pair covers their behinds with high-level tests, and the pair responsible for the connecting story is so busy working out how their piece fits into the puzzle that they don’t have the mental space to hunt down and extend the previous pair’s test. You have two or more high-level tests for the same feature, and duplicate implementations of components. Nobody has visibility into this, because everybody is busy working out what their story means, or is busy implementing it. The new developers on the team are busy enough working out how the product works.
It no longer makes sense for developers to look at the backlog of work, because it’s meaningless to them: on a given day, a pair is assigned to work on a specific track, so they look at the stories labeled as such.
What happens next? The above situation either continues, gets worse, or it improves. The latter only happens if something changes. Next up, you try to split the team.
The whole team wants this, but there are forces against it: emotional ties within the team, worries about practicality, and no obvious place to split in the code. Everything was previously developed with the assumption that everyone understood all components of the system.
Eventually a split occurs anyway. Meetings are a lot shorter, and it feels easy to go back to iterative stories. Now, however, there’s not enough synchronization and the two teams are still working on the same code.
If you’re reading this thinking that I have some solutions to these problems, you’re wrong. Assuming that there is an alternative strategy, what is it? Do we enforce large stories to avoid the ‘incremental story’ problems described above? Is more architecture up-front needed to predict required team splits? Perhaps the issues I’ve described are natural and unavoidable consequences of going fast. Perhaps Fred Brooks is still right, even given the sophisticated team organisational structures we have now.
Can we go fast and keep control?
Refactoring is the process of changing the internal structure of code without changing its external behavior. Successful refactorings involve taking very small, sometimes tedious, steps. Fortunately, many refactorings are simple enough to be automated. In this post, we’ll look at automated refactorings in RubyMine on OS X.
When the name of a variable, method, or class doesn’t explain its purpose, rename it with
shift + F6.
Help explain complex expressions by introducing variables with
command + option + V.
Move related logic into a separate method with
command + option + M.
Inline Variable or Method
Inline variables and methods that don’t increase clarity with
command + option + N
Less frequently used refactorings, such as extracting a superclass or module, are available from the “Refactor This…” dialog,
control + T.
Automation Makes a Difference
Refactoring is a significant part of everyday development. It’s the final step in TDD’s mantra of red, green, refactor. We often refactor inherited code to help us better understand it. Automating refactoring encourages more refactoring. If a simple class rename involves
sed, then it’s time to upgrade to an IDE.