I have been spending a large portion of my time reviewing my design for an application I’m working on… and part of it involves deciding whether what I wrote made sense.
When I was reading through my code, I saw that certain portions of the code had comments. They seemed innocent enough, basically explaining my thought process and what was the purpose of a given method or the next set of code lines. I thought that I was providing good information to whoever would need to read it (including myself).
However, as I’ve been learning more about good software development practices, I realized that the comments I wrote were written purely because the code wasn’t written intuitively. Without the comments, the lines of code were unclear. I wasn’t quite sure why I did what I did, especially since it was weeks since I first wrote it.

So, I found the following two actions to greatly help improve the readability of my code.

Usage of Named Variables

Now, this doesn’t mean use “iterator” instead of i. This means using variable names that explain why I did what I did. Said in another way, use the names to explain the reasoning.

For example, in Tic Tac Toe, when determining the computer player’s next move, part of the logic is to determine which is the shortest path to winning the game.

So, in the portion of the code that checks if the player is going win, I explained that conditional check as such:

win_exists = [conditional_check]
if win_exists
  [do_something]
else
  [do_something_else]
end

This makes it a lot clearer as to why I “do_something” instead of “do_something_else”.

Usage of Good Method Names

A method should explain the behavior, i.e. what is the action that it is going to be performed.
It is good practice to keep the method size small, as well. If there are too many lines of code in a method, splice them out into smaller methods.

For example, in Tic Tac Toe, when setting up the home screen to start the game, instead of having a large setup method that wires everything up, I have the setup method call smaller methods that each explain what they are doing. Below, each line in the “setup_the_game” method calls helper methods that have a single responsibility and have names that explain that.

def setup_the_game
  display_introductory_message
  display_language_config_option
  display_match_options
  inquiry = language_configuration_requested?
  request_language_setup = inquiry.feedback
  if request_language_setup
    configure_language
  else
    [do_something_else]
  end
end

I find it useful when things read like a story. It helps me understand the code better, as well as other people that may have to read it or troubleshoot it.