cookpad / styleguide

Cookpad's coding style guides

Style guides in COOKPAD

Guides

• Ruby (Japanese, English)
• Objective-C (Japanese)
• Swift (Japanese, English)
• Android Java (Japanese, English, Android Studio settings)
• CoffeeScript (Japanese)
• Python (English)

Keywords

• "MUST" means required. Developers must abide by these conventions before merging into master.
• "SHOULD" means recommended. During code reviews, it is common for many small issues to be raised. While it is not critical for developers to fix all of these notes, they are encouraged to stay as close to the style guidelines as possible.

License

Creative Commons Attribution (CC-BY 3.0)

styleguide's Issues

Use `$` prefix for variables which indicates jQuery objects

In common way, we use the variable named with $ prefix for jQuery Objects.
We should consider to use this rule into our CofeeScript guideline.

http://lab.abhinayrathore.com/jquery-standards/

Style guide for Swift in English

Global iOS team currently lacks style guile and we would like to use the company one, but there is only Japanese version available.
I think it would be better to have a unified rules for all teams within company, I will try to translate our Japanese guide to English for us to use it.

Python style guide

We use Python for machine learning and data mining a lot. I'd like to compile a style guide for Python. Some questions to python users:

1. do you depend on python 2 or can we make python 3 default?
2. do you use pep8 or similar linter?
3. what testing framework do you use?
4. do you put your code in jupyter notebooks or .py files, or both?

Inconsistency of the Hash literal rules?

Rule 1:

[MUST] Put whitespaces between { and the first key, and between the last value and } when you write hash literal in multiple lines.

[MUST] 複数行に渡るハッシュリテラルを書くときは、{ と第一要素のキーとの間、および_最終要素の値と } との間に_それぞれ空白を一つずつ入れること。

Rule 5:

[MUST] For multiline hashes, write the first item just after {, increment the level of indentation after the second items, put } on an independent line, and align the line of { to the head of the line of the first item.

[MUST] ハッシュリテラルを単独で複数行で書く場合は、{ の後に第一要素を書き、第二要素以降のインデントを1レベル下げ、} は独立した行に置いて { を書いた行の行頭にインデントを揃える。

I suppose Rule 1 and 5 conflict.

Rule 1 seems to intend that the last value of a hash and its } are in the same line, like this:

{ hoge: 1,
  fuga: 2 }

though currently the example of Rule 1 is basically same as the one of Rule 5:

# good
{ hoge: 1,
  fuga: 2,
}

Upgrade Swift style guide to Swift 3.0

Ruby: Revise a rule related to optional arguments and keyword arguments

Rubocop 0.80.0 (released 2020-02-18) removed Style/BracesAroundHashParameters cop. rubocop/rubocop#7641 says the removal was because the curly braces may have the meaning since Ruby 2.7.

styleguide/.rubocop.yml

Lines 264 to 266 in 590bca6

	# [SHOULD] Omit `{ }` of a hash literal, when put on the end of an argument list.
	Style/BracesAroundHashParameters:
	EnforcedStyle: no_braces

I think it's a good time to reconsider the above rule.

My opinion is:

• Remove Style/BracesAroundHashParameters from .rubocop.yml.
• Rewrite the rule in English and Japanese to mention keyword arguments and hash. Ref: rubocop/ruby-style-guide#788

Any thoughts?

How to name packages in Java?

There is no package naming convention in Java style guide.
I want to know how to name packages with two or more words.

Which of these is better?

• com.cookpad.fooBarBaz
• com.cookpad.FooBarBaz
• com.cookpad.foo_bar_baz
• com.cookpad.foobarbaz

Ruby: Different outputs of good/bad example in "Method calls" section

In the following code example, the output of "good" code and that of "bad" code are different.

https://github.com/cookpad/styleguide/blob/6866d5cebe0881d8c60d9e3f2b4341ddcbb65521/ruby.en.md#method-calls

• [MUST] Use { } form (i.e. brace blocks) for blocks of method calls where the return value of the block used. e.g. as an argument of the other method call.

# good
puts [1, 2, 3].map {|i|
  i * i
}

# bad
puts [1, 2, 3].map do |i|
  i * i
end

irb on Ruby 2.7:

irb(main):001:1* puts [1, 2, 3].map {|i|
irb(main):002:1*   i * i
irb(main):003:0> }
1
4
9
=> nil
irb(main):004:1* puts [1, 2, 3].map do |i|
irb(main):005:1*   i * i
irb(main):006:0> end
#<Enumerator:0x00007fa531910b58>
=> nil

This is due to their different precedence levels. Is this intended? If not, is there any better example?

Layout/SpaceInsideBlockBraces is unnecessarily stricter than the style guide

The Ruby style guide explicitly allows both of the following styles. The official Rubocop configuration accepts only the latter.

# good
[1, 2, 3].each {|num| puts num }
[1, 2, 3].each { |num| puts num }

There seems no way exists to allow both styles without entirely disabling Layout/SpaceInsideBlockBraces (unwanted styles such as [1, 2, 3].each{|foo| bar} will also be allowed).
Is that an option?