sanger/sequencescape

Classes and modules are the units of reuse and release. It is therefore considered good practice to annotate every class and module with a brief comment outlining its responsibilities.

Example

Given

class Dummy
  # Do things...
end

Reek would emit the following warning:

test.rb -- 1 warning:
  [1]:Dummy has no descriptive comment (IrresponsibleModule)

Fixing this is simple - just an explaining comment:

# The Dummy class is responsible for ...
class Dummy
  # Do things...
end

Classes and modules are the units of reuse and release. It is therefore considered good practice to annotate every class and module with a brief comment outlining its responsibilities.

Example

Given

class Dummy
  # Do things...
end

Reek would emit the following warning:

test.rb -- 1 warning:
  [1]:Dummy has no descriptive comment (IrresponsibleModule)

Fixing this is simple - just an explaining comment:

# The Dummy class is responsible for ...
class Dummy
  # Do things...
end

A module is usually a mixin, so when an #initialize method is present it is hard to tell initialization order and parameters so having #initialize in a module is usually a bad idea.

Example

The Foo module below contains a method initialize. Although class B inherits from A, the inclusion of Foo stops A#initialize from being called.

class A
  def initialize(a)
    @a = a
  end
end

module Foo
  def initialize(foo)
    @foo = foo
  end
end

class B < A
  include Foo

  def initialize(b)
    super('bar')
    @b = b
  end
end

A simple solution is to rename Foo#initialize and call that method by name:

module Foo
  def setup_foo_module(foo)
    @foo = foo
  end
end

class B < A
  include Foo

  def initialize(b)
    super 'bar'
    setup_foo_module('foo')
    @b = b
  end
end

Classes and modules are the units of reuse and release. It is therefore considered good practice to annotate every class and module with a brief comment outlining its responsibilities.

Example

Given

class Dummy
  # Do things...
end

Reek would emit the following warning:

test.rb -- 1 warning:
  [1]:Dummy has no descriptive comment (IrresponsibleModule)

Fixing this is simple - just an explaining comment:

# The Dummy class is responsible for ...
class Dummy
  # Do things...
end