gistfile1.md

The researcher believes that well written code should be self-documenting. Ruby code can be so similar to pseudo-code that descriptive commenting would only paraphrase the contents of the line, and could in fact make code less clear.

Below are some code samples from the project to demonstrate the self-descriptive nature of code.

validates_presence_of :password, :on => :create

This line tells the current model that it should validate the presence of a password when it is created.

This is a snippet from sessions_controller.rb, first uncommented, and then with 'descriptive' comments:

user = User.find_by_username(params[:username])
  if user && user.authenticate(params[:password])
    sign_in_as user
    redirect_to account_url, :notice => "Logged in!"


# Find a user by the username given in the `username` parameter
user = User.find_by_username(params[:username])
  # If there is a user, and they can be authenticated by the `password` parameter...
  if user && user.authenticate(params[:password])
    # Sign in as the user
    sign_in_as user
    # Redirect to the account page url with a notice saying "Logged in!"
    redirect_to account_url, :notice => "Logged in!"

In Ruby, comments are understood to serve the purpose of explanation; to explain programming decisions, to simplify complex routines, and to aid future maintainers. In this development, explanatory comments were rarely required, and the researcher understands this to be a good thing.