Terminally Incoherent

When you run a blog such as this one you usually learn to live with writers block or you quit early. Or perhaps not “writers block” itself but just lack of good ideas for blog posts. My usual way of dealing with it is to go trawling the web for inspiration. When you stay cooped inside your own head for a while you sort of get into a self referential funk that might be hard to break out of unless you get some fresh perspectives and ideas from the outside. So I usually hit programming subs on Reddit, Hacker News and/or my RSS feeds to see if I can get excited about something enough to get a blog post of two out of it.

The side effect of such a fishing expedition is that you sometimes find blog posts that are exactly up your alley, but which tackle the subject so well that they leave precious little for you to add to. So then you are left with a choice of either linking to said block and saying “I agree with what that guy said” or blatantly plagiarizing it and hoping no one finds out. The other day I stumbled onto just that kind of article: one that I would love to have written.

The funny thing is that a lot of the ideas in that post were sort of in the back of my mind lately. I have been doing a lot of thinking about code readability, formatting rules and style guidelines for a lot of languages. I have been doing a lot of jumping around between PHP, Python and Ruby lately and I’ve been noticing how each of these languages approaches code style. Python for example strictly enforces proper indentation by making it part of the language syntax, coercing you to write code certain way. This of course doesn’t mean you can’t write atrocious python code, but it is generally harder to do than with say PHP.

The way code is presented definitely impacts it’s readability. I’m not just talking about the usual code guidelines such as using descriptive variable names and structuring your code the right way. I’m talking about purely aesthetic properties of code: consistent indentation style, short line length, alignment of elements in declarative blocks and etc.. go a long way in making the code easier to digest understand. This is the gist of the argument put forth in Dave Copeland’s recent Source Code Typography post: the way you indent and align your code matters.

For the lazy, let me re-use one of his examples: a snippet of a pretty common code you could find in a Ruby on Rails application:

1
2
3

def text_field_tag(name, value = nil, options = {})
  tag :input, { :type => "text", :name => name, :id => sanitize_to_id(name), :value => value }.update(options.stringify_keys)
end

This is fairly concise, albeit ugly code that scrolls off the page in most editors. Unless you have a decent sized screen you can’t actually look at the whole line without scrolling – and even then the length of it makes it impossible to figure out what is going on here at a glance. Dave argues that a very simple re-formatting can drastically increase the readability of the above code:

1
2
3
4
5
6
7
8
9
10

def text_field_tag(name, value = nil, options = {})
  tag :input,
      {
           :type  => "text",
           :name  => name,
           :id    => sanitize_to_id(name),
           :value => value
 
      }.update(options.stringify_keys)
end

I’m not going to re-iterate the entire post here – I recommend you just go and read it yourself. Dave makes some excellent points, especially with regards to the annoying leading comma convention that has become fashionable in the JavaScript community lately. What I want to do is add to his article by pointing out that there are tools you can use to make formatting code easier.

For example, to keep your code lines relatively short it is a good idea to set up your editor or IDE to highlight column 80 giving you a visual indication as to how wide your code ought to be. This provides a soft boundary that you can go over if needed. In Vim this can be done via a single line added to your .vimrc:

hilight ColorColumn guibg=lightyellow ctermbg=227

You can of course substitute lightyellow and 227 to your choice of colors – I picked these because light yellow goes well with my Solarized Light theme: it is visible, distinct but not too jarring:

Column 80 Highlighted

Similarly, when you need to re-align some code (as in the example above) there exist two plugins that will do the job for you: Vim-Align and Vim-Tabular. The later is the newer, more feature rich plugin and there is an excellent Vimcast on it that you can watch here. Both essentially help you align blocks of code based on some sort of a token. They make a task that can be quite labor intensive (a lot of moving around and tabbing) into a two step process: select block to be aligned, then issue the alignment command such as:

" tabular.vim
:Tab /=>
 
" align.vim
:Align =>

In both cases alignment is usually done while respecting your tabs/spaces settings ensuring that things don’t completely break apart next time you re-tab your file (using g g = G).

How do you ensure that your code is optimized of maximum readability? Do you have any plugins or tricks for your favorite text editor you would like to share? Let us know in the comments.

If you are following the recent trends in the Vim community you have probably noted the ever growing popularity of Powerline. As the name suggests, it is a very powerful status line generation plugin, but I don’t think that’s why most people use it. I believe its popularity has a lot to do with how sexy it looks on the bottom of your screen.

To be honest, I was never that fond of that particular extension for a variety of reasons. One of my chief gripes with it is directly related to the way it looks. Powerline uses non-standard patched fonts in order to achieve that segmented look which is not something Vim supports natively. Without them the extension looses a lot if it’s sex-appeal and starts looking a bit plain. To configure it, you don’t just add entries to your .vimrc but instead you need to create a separate dot-folder where it’s settings files are kept. While this neatly separates the Powerline setup from general Vim settings it also adds maintenance headaches. I like to keep all my Vim related config files in a single directory under source control so you can imagine this is less than optimal.

Finally, I have never really felt like I would use any of it’s advanced features. Most of the power-line setups I see on screenshots and in screen-casts are very basic: mode indcation, file path, some file and cursor position info. All of that can be easily set up in just a few lines of VimL. Powerline on the other hand is a monstrous semi-framework that can let you do really frivolous and complex things. For example, it has support for hooking into your power management module by the way of python and displaying battery status in Vim. It can also pull weather notifications from the web and display them in your status line… Though why would you ever want that is beyond me.

It is really a nice an powerful plugin, but it doesn’t seem like something I would necessarily need. For years I have been pretty happy using a very simple status line with just the name of the file and some positioning info along side the excellent Obvious-Mode plugin. It covered most of my needs – my status line would be red in insert mode, gray/cyan in normal mode, depending on whether or not the file had any unsaved changes.

Lately however I decided that I could use more informative status line. I briefly flirted with the concept of using Powerline but since I’m a system nomad who drags his .vim folder wherever he goes that idea died pretty quickly. Instead I decided to create my own status line which displays the information that I care about in a Powerline-like way but without any fancy fonts.

The killer feature for me is that I wrote it. By that I mean that if something breaks or doesn’t work correctly can easily figure out why, and fix it. Power line is pretty big and has a lot of moving parts, whereas my status line is just a dozen lines of very basic VimL so if it breaks, I can easily handle it without loosing too much time.

The result looks like this:

Vim-NeatStatus Plugin

The mode indicator on the left changes color depending on the mode: green in normal, red in insert and blue in replace mode. I also had it turn purple in visual mode but it was kinda buggy (always lagged one keystroke behind) so at the moment it doesn’t do that. I still use Obvious-Mode so this functionality isn’t strictly necessary, but I included it so that it could be used as a stand-alone plugin.

The black box next to mode indicator shows you the server name (which in my case is treated as session name). This may not be useful to everyone, but since I set up my Vim to save sessions on exit I actually like to see that information somewhere.

To the left of the file path I have file type (ie. what language vim thinks this file is written in), file format (important if you jump between systems as much as me) and encoding (as in utf8 or not). The last may not seem fairly relevant to you, but sometimes it does matter: especially if you are trying to parse files in a certain way, or if you create a script that doesn’t run properly because the non-vim text editor decided to insert a BOM in it for shits and giggles.

Next I have the buffer number (which is useful when you have a lot of buffers open) and cursor positioning info with the current line highlighted in pink to stand out and be easily readable. There is also one more bit that is not visible in the picture above: whenever you edit a file, a little pink notification appears in the right corner of your status bar to let you know that the file has unsaved changes. Once again this is a duplication of Obvious-Mode functionality but it can be useful if you decide to install it as a stand-alone.

The colors work both in the graphical Vim as well as in the console (though you may need one that supports 256 colors). I tested it in in Gvim, MacVim and using Gnome-Console as well as Cygwin MinTTY on Windows.

I made the entire thing available as a plugin that can be easily installed via Pathogen like this:

cd ~/.vim/bundle
git clone git://github.com/maciakl/vim-neatstatus.git

If you have your .vim under source control like me then do:

cd ~/.vim
git submodule add git://github.com/maciakl/vim-neatstatus.git bundle/vim-neatstatus
git submodule init
git submodule update

At the moment the colors are hard coded and the plugin is not very configurable as a whole, but that will likely change in the future. If something is broken or the colors look atrocious under some setups let me know and I will try fixing it.

Are you able to change the status line in your favorite text editor? If yes, what kind of information do you put there? Have you written your own status line or are you using a plugin written by someone else?