Opera Mail or Alternative To Google Reader

I’ll keep this short.

Google Reader is dead. Chrome does not have a built-in RSS reader. Opera does, it’s called Opera Mail. It looks like this:

You subscribe to feeds by navigating to the RSS feed and clicking on a nice big subscribe button:

Tutorial on How to write a Haskell Tutorial

Over the course of reading many tutorials and examples for Haskell and it’s libraries, I can say that there are some things that are an absolute requirement for making it easier for readers to understand your code. Here are the things I think should be in every tutorial or teaching example of Haskell code.

Explicit Imports

This is so important that it has to be #1. To be able to figure out where a given type or function comes from, always full qualify what you are importing from where.

For example, in the code below, where do the functions ask and put and the types Query and Update come from?

module Test where 

import Data.Acid
import Control.Monad.State
import Control.Monad.Reader

data MyState = MyState String deriving (Show)

writeState :: String -> Update MyState ()
writeState val = put (MyState val)

queryState :: Query MyState (Maybe String)
queryState = do MyState str <- ask
	    return $ Just str

Now if we write it like this, things become much clearer:

module Test where 

import Data.Acid (Update, Query)
import Control.Monad.State (put)
import Control.Monad.Reader (ask)

data MyState = MyState String deriving (Show)

writeState :: String -> Update MyState ()
writeState val = put (MyState val)

queryState :: Query MyState (Maybe String)
queryState = do MyState str <- ask
	    return $ Just str

which brings me to the next point.

Explicit Imports of Prelude types

You may know that Maybe monad is imported by the Prelude, but most of the new users will often get confused. So, yes, import the Prelude types and functions explicitly.

import Data.Maybe (Maybe)
import Data.Acid (Update, Query)
import Control.Monad.State (put)
import Control.Monad.Reader (ask)

data MyState = MyState String deriving (Show)

writeState :: String -> Update MyState ()
writeState val = put (MyState val)

queryState :: Query MyState String
queryState = do MyState str <- ask
	    return str

Put Source in Single File

When a new user is getting acquainted with the new library or framework, the last thing he needs to worry about is file or module structure. The user needs to see how components interact with each other. Keeping all the source code in one file (even if long) allows the user to quickly to a text search for a relevant piece of code.

Later tutorials or examples may show the best way to structure the application. In fact, this is what most frameworks provide in a form of starter app or a project template.

Err on the side of More Comments

Even if you are writing a tutorial, and showing snippets of code, it does not hurt to put comments in that code as well. For example:

-- We'll need this for return types
import Data.Maybe (Maybe)
-- Basic return types for our pure query functions
import Data.Acid (Update, Query)
-- These will allow use to manipulate state
import Control.Monad.State (put)
import Control.Monad.Reader (ask)

-- What we will persist
data MyState = MyState String deriving (Show)

-- Store a string in a state
writeState :: String -> Update MyState ()
writeState val = put (MyState val)

-- Retrieve a maybe value from the state.
queryState :: Query MyState String
queryState = do MyState str <- ask
	    return str

while this code may be a nightmare to read or maintain in a real application or for a professional Haskell developer – to a newbie every line is like a piece of gold, clarifying some concepts he or she didn’t completely grasp or understand.

Provide Library Versions

For every library that you import or reference, provide an exact version that the code you wrote will run with. Haskell is a fast developing ecosystem, and things get broken all the time. For a newbie it is not important that they work with the latest libraries when learning. All they needs is to grasp the concepts and ideas. After which they will be able to go out on their own and infer how these things should work in future versions.

The easiest way to satisfy this requirement would be to include .cabal file with your tutorial or example, which has the Build-depends directive. You can easily and interactively create a .cabal file for you code with the following command, which you should run inside your source code directory:

cabal init

Explain Difficult Type Signatures

One of the most difficult things for a newbie to figure out is all the types everywhere. So when you have a complicated looking type, take your type to explain what is going.

For example, Acid State tutorial does a great job with this when they explain this type signature:

 update' :: (UpdateEvent IncCountBy, MonadIO m) =>
             AcidState (EventState IncCountBy)
             -> IncCountBy
             -> m (EventResult IncCountBy)

and here is the explanation:

EventState is a type function. EventState IncCountBy results in the type CounterState. So that reduces to AcidState CounterState. So, we see that we can not accidently call the IncCountBy event against an acid state handle of the wrong type.

Figuring out the Label and Caption in LaTeX

Sometimes, when you place the label and caption inside the figure out of order, you get weird numbering in your document when you go to reference that figure. What many people don’t realize is that there is a reason for this madness and it is much easier to understand why this happens, then to try and remmember the order in which these things should go.

Why this happens

Perhaps if people know why this happens, it will be much easier to remember what goes where.

Short version

Caption command within a figure or table acts much like a sectioning command within the document. So if you don’t put a caption, the label has nothing to “label”, and the closest thing it can find is a section in which you are in.

Longer version

To understand what is going on we must establish a few things. First, a label command when placed anywhere in the document will label the section of the document in which it is places. So something like this:

Section \ref{sec-one} is great!  

\subsection{First section}
\label{sec-one} 

This is the first section

Will produce:

Section 2.11 is great!

2.11 First section
This is the first section

Second, label command appearing in a numbered environment acts differently. Numbered environments are things like equation, eqnarray, enumerate, figure, table… In each of these environments the label command acts differently. For example, in eqnarray environment the label can go anywhere before the \\ that ends the current equation - effectively giving each equation it’s own label!

The figure environment has different rules. In particular, the thing that creates numbering inside the figure environment is the caption command. A figure may have multiple captions, creating multiple “sections” within the figure. On other hand, if the caption command is never used, the label still uses the text numbering (which is the number of the section of the document it is in).

Remember: A figure may have multiple captions

So, if we have something like:

\begin{figure}
  BLAH
  \label{sec:one}
  \caption{Blah figure!}
  \label{fig:blah}
\end{figure}

we now know that Section \ref{sec:one} will refer to the section of the document in the text and will produce something like Section 2.11.

While Figure \ref{fig:blah} will actually refer to the thing we want and will produce something like Figure 1.

Conclusion

Since it is difficult to remember which goes first, caption or label, inside your figure, understanding why the order matters completely removes the need for memorization. Since the caption command is responsible for sectioning the figure environment, we know that we must call it at least once before using the label command. By knowing the why we can immediately deduce the how. And that, makes all the difference!

Reference

I would be lying if I said that I figured this out (no pun intended) on my own. The book “LaTeX: A Document Preparation System (2nd Edition)” by Leslie Lamport—as old as it is—was the primary source for my understanding of this topic.

Better Vim Configuration

Having gotten tired of constantly re-configuring my Vim on every computer, I’ve decided to create a Git repository to store all the stuff. I’ve made it public, available for anyone to use: https://bitbucket.org/drozdyuk/vimfiles

What are the advantages of using Git to manage your Vim configuration?

1. Good base to start from. You don’t need to fight with the ugly default configuration of Vim.

2. Better plugin management. By using Git, you can take advantage of Git’s submodules feature, which allows you to easily fetch up-to-date Vim plugins straight from their repositories.

3. Useful Plugins. My Git repository comes with a minimal number of useful plugins, which are tested and working. If you want you can easily add more!

On Programming

Writers write. They say that if you want to be better at writing the only way to do it is to sit down and write. There is no other way. Reading books on “becoming a better writer” and going to “inspiration” workshops won’t help; there is no manual on how to become a famous writer. Because if there was, then anyone could become a great writer, publish a great book, and make a lot of money. And most of the writers I know, are far from millionaires.

The only way to get better is to write. A lot.

If you are a programmer - you write. You write a lot. You write every day. You write at work, at home, in the morning, in the evening, and sometimes even when you sleep. Whether you write for work or for fun, is irrelevant. Most writers don’t write at “work” and then at home. Their writing consists of about three hours every day (unless they are journalists of course). Compare that to the fifteen hours for most programmers.

Isn’t it curious then, how being a writer is regarded so highly by many people, as being a hard occupation? Nevertheless, writer is a much older occupation than a programmer, so we could probably learn a thing or two from them.

Workday

The very same work day of three hours per day, mentioned earlier, is not just a random number, made up randomly by writers because they are lazy. It is there exactly because that is the extent of how much creative work a human can do to their full potential during the day. So, when you say that you work ten hours a day, how much work are you really doing?

Elementary principles

Here I will blatantly rip off the writers’ bible The Elements of Style, which details some of the core principles that most writers must follow. While these rules are not agreed upon by all, it is the consensus that if you want to break the rules, you must, at least, know what they are.

Choose a suitable design and hold to it

Writing, to be effective, must follow closely the thoughts of the writer, but not necessarily in the order in which those thoughts occur.

Here, programmers, perhaps, have an upper hand, as setting down their thoughts in code is arguable easier (at least easier to check if what they wrote meets their expectations) than it is for writers to set down their thoughts on paper in a clumsy and imprecise language, such as English. In the next part, we are probably as much to blame as anyone else:

The first principle of composition, therefore, is to foresee or determine the shape of what is to come and pursue that shape.

How often have you plunged into coding (“writing”), without first thinking of what it is you are trying to achieve, only to find yourself, two days later, lost in the heaps of methods and classes that have become so intertwined that you can no longer understand how your masterpiece works?

Keep related words together

This next piece of advice, took me about ten years to understand.

The position of the words in a sentence is the principal manes of showing their relationship. Confusion and ambiguity result when words are badly placed. The writer must, therefore, bring together the words and groups of words that are related in thought and keep apart those that are not so related.

I was always taught to break up my code into functions; sometimes even put a bunch of functions into a separate file. The focus was always on breaking code into smaller pieces, emphasizing reuse and avoid copying. But nobody ever told me that I should group related functions, variables and other things close together - so that they would be easy to read, without jumping from one file to another. After all, if you are reading a novel, you can’t imagine jumping to footnote and then back over to main text - this would distract from the main flow of the story! So why, if I am reading you code, should I jump from one file to another and another to figure out exactly what story you are telling me?

Conclusion

While I could go on and try to stretch this even further, I won’t. What I am trying to say is that if writers, who were around for thousands of years, still can’t get their stuff right - need to practice their craft every day and read rule books to not forget how to do what it is they do - how can such a young profession as a programmer claim to be perfect in it’s practice? You cannot afford to stop learning and refining the way you learn. And maybe, take a few tips from other older professions. Unless, of course, you want to stay a journalist all your life.