源代码排版

2018-02-24 16:10 更新

所有风格都又丑又难读,自己的除外。几乎人人都这样想。把“自己的除外”拿掉,他们或许是对的...
——Jerry Coffin(论缩排)

  • 使用 UTF-8 作为源文件的编码。
  • 每个缩排层级使用两个空格。不要使用硬 tab。

    # 差 - 四个空格
    def some_method
        do_something
    end
    
    # 好
    def some_method
      do_something
    end
  • 使用 Unix 风格的换行符。(BSD/Solaris/Linux/OSX 的用户不用担心,Windows 用户要格外小心。)

    • 如果你使用 Git ,可用下面这个配置,来保护你的项目不被 Windows 的换行符干扰:
    $ git config --global core.autocrlf true
  • 不使用 ; 隔开语句和表达式。推论——一行一条语句。

    # 差
    puts 'foobar'; # 不必要的分号
    
    puts 'foo'; puts 'bar' # 一行里有两个表达式
    
    # 好
    puts 'foobar'
    
    puts 'foo'
    puts 'bar'
    
    puts 'foo', 'bar' # 仅对 puts 适用
  • 对于没有成员的类,尽可能使用单行类定义。

    # 差
    class FooError < StandardError
    end
    
    # 勉强可以
    class FooError < StandardError; end
    
    # 好
    FooError = Class.new(StandardError)
  • 定义方法时避免单行写法。尽管还是有些人喜欢这么用的。但是单行定义很容易出错,因为它在语法上有些古怪。无论如何——一个单行方法里的表达式不应该多于 1 个。

    # 差
    def too_much; something; something_else; end
    
    # 勉强可以——注意第一个 ; 是必需的
    def no_braces_method; body end
    
    # 勉强可以——注意第二个 ; 是可选的
    def no_braces_method; body; end
    
    # 勉强可以——语法上正确,但是没有 ; 让它有些难读
    def some_method() body end
    
    # 好
    def some_method
      body
    end

    这个规则的一个例外是空方法。

    # 好
    def no_op; end
  • 操作符前后的空格。在逗号 , 、冒号 : 及分号 ; 之后,在 { 前后,在 } 之前。 Ruby 解释器(大部分情况下)忽略空格。但要写出可读性高的代码,正确使用空格是关键。

      sum = 1 + 2
      a, b = 1, 2
      1 > 2 ? true : false; puts 'Hi'
      [1, 2, 3].each { |e| puts e }

    (针对操作符)唯一的例外是当使用指数操作符时:

      # 差
      e = M * c ** 2
    
      # 好
      e = M * c**2

    { 和 } 需要额外说明,因为他们是用在块(block)、 哈希字面量(hash literals),以及字符串插值中。 对于哈希字面量来说,两种风格都是可接受的。

      # 好——`{` 之后和 `}` 之前有空格
      { one: 1, two: 2 }
    
      # 好——`{` 之后和 `}` 之前没有空格
      {one: 1, two: 2}

    第一个种风格稍微更具可读性(而且有争议的是,一般在 Ruby 社区里更受欢迎)。 第二种风格具有可为块和哈希字面量添加可视化的差别的优点。 无论你选哪一种都行——但是最好保持一致。

  • ( 、 [ 之后, ] 、 ) 之前,不要有空格。

    some(arg).other
    [1, 2, 3].length
  • ! 后不要有空格。

    # 差
    ! something
    
    # 好
    !something
  • 范围表达式中间不要有空格。

    # 差
    1 .. 3
    'a' ... 'z'
    
    # 好
    1..3
    'a'...'z'
  • 把 when 跟 case 缩排在同一层。我知道很多人不同意这一点,但这是《The Ruby Programming Language》及《Programming Ruby》所使用的风格。

    # 差
    case
      when song.name == 'Misty'
        puts 'Not again!'
      when song.duration > 120
        puts 'Too long!'
      when Time.now.hour > 21
        puts "It's too late"
      else
        song.play
    end
    
    # 好
    case
    when song.name == 'Misty'
      puts 'Not again!'
    when song.duration > 120
      puts 'Too long!'
    when Time.now.hour > 21
      puts "It's too late"
    else
      song.play
    end
  • 当赋值一个条件表达式的结果给一个变量时,保持分支的缩排在同一层。

    # 差 - 非常复杂
    kind = case year
    when 1850..1889 then 'Blues'
    when 1890..1909 then 'Ragtime'
    when 1910..1929 then 'New Orleans Jazz'
    when 1930..1939 then 'Swing'
    when 1940..1950 then 'Bebop'
    else 'Jazz'
    end
    
    result = if some_cond
      calc_something
    else
      calc_something_else
    end
    
    # 好 - 结构很清晰
    kind = case year
           when 1850..1889 then 'Blues'
           when 1890..1909 then 'Ragtime'
           when 1910..1929 then 'New Orleans Jazz'
           when 1930..1939 then 'Swing'
           when 1940..1950 then 'Bebop'
           else 'Jazz'
           end
    
    result = if some_cond
               calc_something
             else
               calc_something_else
             end
    
    # 好 ( 避免代码让行宽过长 )
    kind =
      case year
      when 1850..1889 then 'Blues'
      when 1890..1909 then 'Ragtime'
      when 1910..1929 then 'New Orleans Jazz'
      when 1930..1939 then 'Swing'
      when 1940..1950 then 'Bebop'
      else 'Jazz'
      end
    
    result =
      if some_cond
        calc_something
      else
        calc_something_else
      end
  • 在 def 之间使用空行,并且用空行把方法分成合乎逻辑的段落。

    def some_method
      data = initialize(options)
    
      data.manipulate!
    
      data.result
    end
    
    def some_method
      result
    end
  • 函数最后一个参数后面不要加逗号,特别是每个参数单独一样的时候

    # 差 - 虽然移动和增删参数的时候会很简单,但仍不推荐
    some_method(
                 size,
                 count,
                 color,
               )
    
    # 差
    some_method(size, count, color, )
    
    # 好
    some_method(size, count, color)
  • 当给方法的参数赋默认值时,在 = 两边使用空格:

    # 差
    def some_method(arg1=:default, arg2=nil, arg3=[])
      # 做一些任务...
    end
    
    # 好
    def some_method(arg1 = :default, arg2 = nil, arg3 = [])
      # 做一些任务...
    end

    虽然几本 Ruby 书建议用第一个风格,不过第二个风格在实践中更为常见(并可争议地可读性更高一点)。

  • 避免在不需要的时候使用行继续符 \ 。实际编码时,除非用于连接字符串, 否则避免在任何情况下使用行继续符。

    # 差
    result = 1 - \
             2
    
    # 好 (但是仍然丑到爆)
    result = 1 \
             - 2
    
    long_string = 'First part of the long string' \
                  ' and second part of the long string'
  • 使用链式方法时风格统一。社区认为前引点号和末端点号都是好的风格。

    • (可选 A)和当一个链式方法调用需要在另一行继续时,将 . 放在第二行。
    # 差 - 为了理解第二行需要去查阅第一行
    one.two.three.
      four
    
    # 好 - 第二行在做什么立刻变得很清晰
    one.two.three
      .four
    • (可选 B)末尾用点号表示表达式没有结束
    # 差 - 需要读到第二行才能确定表达式没有结束
    one.two.three
      .four
    
    # 好 - 从第一行就可以立即明白表达式没有结束
    one.two.three.
      four

两种方法各自优点参阅这里

  • 方法参数过长时,将它对齐排列在多行。当对齐的参数由于线宽不适合对齐时, 简单的在第一行之后缩进也是可以接受的。

    # 初始(行太长了)
    def send_mail(source)
      Mailer.deliver(to: 'bob@example.com', from: 'us@example.com', subject: 'Important message', body: source.text)
    end
    
    # 差(两倍缩排)
    def send_mail(source)
      Mailer.deliver(
          to: 'bob@example.com',
          from: 'us@example.com',
          subject: 'Important message',
          body: source.text)
    end
    
    # 好
    def send_mail(source)
      Mailer.deliver(to: 'bob@example.com',
                     from: 'us@example.com',
                     subject: 'Important message',
                     body: source.text)
    end
    
    # 好(普通缩排)
    def send_mail(source)
      Mailer.deliver(
        to: 'bob@example.com',
        from: 'us@example.com',
        subject: 'Important message',
        body: source.text)
    end
  • 用字面量构建数组时,如果跨行,应对齐。

    # 差 - 未对齐
    menu_item = ['Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam',
      'Baked beans', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam']
    
    # 好
    menu_item = [
      'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam',
      'Baked beans', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam'
    ]
    
    # 好
    menu_item =
      ['Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam',
       'Baked beans', 'Spam', 'Spam', 'Spam', 'Spam', 'Spam']
  • 大数字添加下划线来改善可读性。

    # 差 - 有几个零?
    num = 1000000
    
    # 好 - 更容易被人脑解析。
    num = 1_000_000
  • 使用 RDoc 以及它的惯例来撰写 API 文档。注解区块及 def 不要用空行隔开。

  • 每一行限制在 80 个字符内。
  • 避免行尾空格。
  • 文件以空白行结尾。
  • 不要使用区块注释。它们不能由空白引导(=begin 必须顶头开始),并且不如普通注释容易辨认。

    # 差
    = begin
    一行注释
    另一行注释
    = end
    
    # 好
    # 一行注释
    # 另一行注释
以上内容是否对您有帮助:
前端开发就业
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号

意见反馈
返回顶部