[RUBY] Foreigners talk: How to name classes and methods in English

I'm a foreigner. I am American. Hello lol

To be precise, I was a Puerto Rican and moved to the United States at the age of one and grew up in the United States all the time, but that's another story.

Purpose of this article

I think many Japanese are not confident in their English ability. Unfortunately, I often hear people say "I don't understand English" or "I can't speak English at all". However, I have met some Japanese who can speak English, and even if it is not perfect, I am sure that my intention was conveyed properly. Being able to convey your thoughts and proceed with your work, rather than being able to speak fluently. I think that is the most important thing to start working on open source programs and English programs (foreigners are also very helpful). In Japanese culture, I rarely boast that "I can do it!", But through this article, I would like to give you a little confidence in how to name your programming, even if you are not fluent. It doesn't have to be perfect. Let's go!

I want you to read it together

Summary of English words often used in programming [Updated from time to time] Reference information for successful method naming 7 things I want you to keep in order not to be a fucking code <-(Especially "Comments Don't try to write it neatly. Put your thoughts into it !!! ”)

Overview

  1. How to write in English
  2. Treat classes, methods and arguments as one sentence, including arguments as much as possible.
  3. Eliminate breaks
  4. Length of variables, pitfalls when omitting

1. How to write in English

I write Ruby normally, but I really like RSpec.

example_spec.rb


it { is_expected.to eq(10) }

Actually, the first time I saw it on RSpec was the deprecated "should", but when I saw something like this, "What !? Is this an ant ?? It's like reading a normal English sentence!" I thought that it left a good impression. But when I think about it, when I started studying Ruby from Java, and when I looked at Python, I got the same impression.

In fact, I think programming languages and frameworks will continue to evolve. In other words, future programs and programming languages will be made up of a group of English words like RSpec and shoulda_matchers. Looking at this way of writing, I think, "Oh, this is good. It's easy to read!" I think other foreigners must think so too.

That is the point here! Implement after thinking about the English text you want to make! </ strong>

It seems natural to write the code in English as much as possible, but the point is not to write in English words </ strong> often, but to write in English sentences </ strong>. Of course, it doesn't have to be a solid English sentence. The ease of use of the code is to create short commands in one bite. Write the English text you want to write, starting from a complete idea of what the class does for what, not just the method you want to write. Take out the paper and write a few sentences! The point is not complicated and long sentences, but simple and comfortable sentences! In particular, I would like to introduce one of the pleasant writing styles in the next item.

2. Treat classes, methods and arguments as one sentence, including arguments as much as possible.

Classes are generally nouns. When making a game, it's called Player, and when making a service, it's called ʻUser`. Objects are something in the first place, so this is easy to understand.

Isn't it often possible to name a method? This is a simple example, but take a look at the following program.

game.rb


Type = ["♥", "♦", "♣︎", "♠︎"]

class Deck

  attr_accessor :cards

  def initialize
    @cards = []
    4.times do |n|
      1.upto(10) do |i|
        @cards.push([Type[n], i])
      end
    end
  end
end

class Player
  def initialize(name)
    @name = name
  end

  def shuffle deck
    deck.cards.shuffle
  end
end

With this way of writing,

player1.shuffle deck

It is quite easy to read.

Recently, I was a little worried when I saw the following writing style.

def shuffle_deck deck
  deck.cards.shuffle
end

It's a name that you can understand just by looking at the method name, but since methods are usually paired with arguments, I think that it will be quite concise if you make a sentence by combining the arguments with the method name. RSpec and shoulda_matchers do just that.

point! The best way to write " subject + verb + object </ strong>" is w Subject = class Verb = method Object = argument

But I have to go with "subject + verb + object"! Not really. I just want to clarify what does what for what.

The following is a slightly more advanced example. I recently wanted to write a method like this. Player has score, and if you win the game, the score will increase. When I thought about the English text, "Add 1 to score" came to my mind. But then it looks like this ...

player.rb


class Player
  def initialize
    @score = 0
  end

  def add(num)to_score
    @score += num
  end
end

player1 = Player.new
player1.add(1)to_score

This is impossible, isn't it? I thought, "But it's easy to read !!! Oh, I want to write a method name like this!" At that time, I came up with the following method

player.rb


def score_increases_by(num)
  @score += num
end

player1.score_increases_by(1)

It's not in the form of "subject + verb + object", but here num is the object of by, so it's clear what the class does for what, and it can be read like an English sentence.

"Player 1's score goes up by num" It's easy to read. With "player1 score" as the subject and num as an argument. Treating classes, methods, and arguments as one sentence makes it easy to read the word order and flow of the sentence, isn't it?

Of course you can write player1.score + = 1, but ww for example!

To give another example ...

object.rb


player1.draw card
player1.send message
player1.forfeit match

etc

Please try this technique by all means.

3. Eliminate breaks

In Ruby, the "?" Method is often used to check true or false.

true_or_false.rb


class Player

  attr_accessor :card, :score

  def initialize
    @card = "♥"
    @score = 0
  end

  def has_heart?
    #Return the truth
    @card == "♥"
  end
end

if player1.has_heart?
  puts "You have a heart!"
end

is this. .. .. I'm a little worried personally. Because I don't say "If player has heart?" In English. It feels like "Ask a sentence that includes If ?? If ... then ... flow?" So where there should be no break, there is a break. It would be better if I replaced it, but it still feels strange ...

true_or_false.rb


puts "You have a heart!" if player1.has_heart?

Why are you asking? It feels like ww But I think it's the "culture" of Ruby, so I don't think it can be changed so easily. (I love Ruby! I don't have a diss! Ww)

I would write

true_or_false.rb


def has_heart
  @card == "♥"
end

if player1.has_heart then
  puts "You have a heart!"
end

With this kind of feeling, I don't feel any discomfort in the relationship with then. Reference information for naming methods "Methods that return boolean values" I think it's good

You might think that it doesn't make much difference, but this leads to code readability. Can you read your code quickly? Is there a break in the sentence that should be said in one shot?

If you feel a break in the "sentence" you want to create, think about the method name, if statement, while statement, etc. and remake it so that you can say it in one shot.

4. Length of variables, pitfalls when omitting

This has nothing to do with English, but I'm curious about it once in a while, so I wanted to write something. In the place of "I want you to read it together", 7 things I want you to keep because it does not become a fucking code I put in . The following was written in the article

Don't leave a comment that asks "why?" !!

The method names, variable names, etc. of the code are the same. Recently I saw the word "Pelmanism" for the first time in my life. English is my first language, but I didn't know what it meant. When I hear the story of the person who introduced the word, "Pelmanism" means "nervous breakdown". For me, "nervous breakdown" has always been called "Memory Game" www

So write the method name etc. so that you and the person reading the code can understand your intentions. Focus on readability to keep the code going, not cool and long English. Simple is the best.

Just be careful to omit it. Have you ever seen such a code?

abbreviations.rb


rlts = db.execute(sql)
rlts.each do |r|
   r = r.to_i
end

I would like to say, "What is rlts in the first place? I don't know at all when it comes to r!" If you write such a code, even if it is a little long, please write the English words as they are so that the intention can be conveyed

abbreviations.rb


results = db.execute(sql)
results.each do |result|
   result = result.to_i
end

Well, it's short, so I think it's okay to change the singular "result" to "res" here, but I think it's important to convey the intention anyway. Therefore, try not to omit English words roughly. If you are not confident, just write the English words.

I think you can omit the frequently used abbreviations and the variables that consist of multiple words. You can see that the db above is a database. The abbreviation is used a lot, so it's ok. If it ’s unfamiliar,

ppap.rb


# pen pineapple apple pen
ppap = Picotaro.new

#It came out ww Is it familiar w

I think you should write it with a comment.

Looking back

I think the most important items are the following two

  1. I want to ride the wave of reality where the way of writing programming is changing more and more like English
  2. Simple and easy-to-understand things lead to work efficiency, not fluent English or methods / variables that fit in one English word.

It may be difficult for me to think "I can do it!", But many Japanese write pretty good code! Let's write easy-to-extend code by sharing easy-to-understand words with everyone!

Do your best! And please enjoy programming in English (^_^)

Recommended Posts