Rubycop outputs messages like:
app/controllers/welcome_controller.rb:1:1: C: Missing top-level class documentation comment.
class WelcomeController < ApplicationController
^^^^^
I wonder what does top-level class documentation look like. It's not just a comment, is it? It needs to have a special format, but which one?
That said a simple comment like so will do nicely:
# This shiny device polishes bared foos
class FooBarPolisher
...
I ended up here looking for a way to disable this check, if that's your case, put
Documentation:
Enabled: false
in your .rubocop.yml file.
From the Rubocop documentation:
RuboCop is a Ruby static code analyzer. Out of the box it will enforce many of the guidelines outlined in the community Ruby Style Guide.
The Ruby Style Guide "comment" section doesn't use the phrase "Missing top-level class documentation comment" but from reading the guide section on comments, you can quickly infer from the examples that commenting classes and modules is recommended.
The reason is, when using rdoc, the comments for the classes/modules will be used to generate the reference to the code, something that is important whether you're writing code for yourself, for a team or for general release by others.
Related
Both . and :: can be used to call class methods, but, in my experience, . is by far the most commonly used of the two. So I am accustomed to using that form in documentation and RSpec describe/context/expect strings.
However, the Ruby API documentation uses :: (e.g. at https://rubyapi.org/3.1/o/string). Is that intended to mean that that form is preferred for the cases I described?
Note: This is not a duplicate of Is there a difference between :: and . when calling class methods in Ruby?. That question refers to the use of the two alternate notations in Ruby source code, whereas this question refers to documentation and other textual descriptions (e.g. in rspec strings). There may be reasons to make different choices in code vs. documentation, for example, that using . in code more clearly indicates a message call vs. a constant access, whereas in documentation :: might be preferred to more dramatically distinguish class methods from instance methods.
As far as I know RuboCop always suggets to use . when calling class method, as explained here.
Looking at documentation you have linked regarding the class String, they seem to use a single . when calling class methods, as seen here.
Actually I was not able to find a code snippet in that doc page that uses the :: notation for calling a class method.
If you are referring to the menu on the left, which uses :: to indicate class methods and # for instance methods, it's a Ruby documentation convention and has no real meaning in actual code.
Maybe this could be an helpful resource.
Is there a difference between the following 2 snippets of code?
# 1st snippet
class A
class B
# some code here
end
end
# 2nd snippet
class A::B
# some code here
end
If there is a difference, can you help me understand what the difference is and why you would use one version versus the other?
This seems to be mostly syntactic sugar for organizing your code - whichever way makes sense to you is the "correct" way. The only exception is that with the 2nd snippet, if class A hasn't already been defined you'll get an error. For the most part this question is a duplicate of this one, though since you are nesting classes in classes instead of classes in a module, I'll go ahead and link the Module docs, which explains the difference between modules and classes in Ruby and may help you interpret that SO answer in the context of your own question.
In C# I can use the #region keyword to separate blocks of code. Does something like it exist in Ruby?
Short answer: no.
Long answer: There is no code folding or comment style convention enforced by the ruby language. You can use your own convention for grouping methods however and setup your text editor to fold code in a way that works well for you (http://vim.wikia.com/wiki/Folding).
Many wont like this answer, but its simple, and it works
if region1=true
#your code/comments here
end #region1
this is of course, if region1 is not a variable you need at that scope
My suggestion: put code you'd have in a C# #region into a ruby module.
A #region comment in C# is used for code folding in Visual Studio. You can group similar code into a region like:
#region Some Info here to see when folded
methodA() {}
methodB() {}
#endregion
If you find yourself asking "is there a ruby equivalent to C Sharp region", it's time to have a look at modules in the ruby language. With modules you can group code AND share code between classes (instead of using inheritance, interface or else).
Example:
class A
module AMod # you can put the module into a file, too
def a_method
# do stuff
end
# some methods
end
include AMod
end
My answer: Use Emacs. It doesn't seem to answer your question, but it does.
I need to create a class that represent "SVN" inside a module called "SCM". But I don't know what is the convention when dealing with acronyms in Ruby, and could not find anything relevant in Google, except "Camel case is preferred".
Should I call it SCM::SVN or Scm::Svn? Is there a convention for this?
Add the following to config/initializers/inflections.rb.
ActiveSupport::Inflector.inflections(:en) do |inflect|
inflect.acronym 'SVN'
end
Now running $ rails g model SVN… will create a class named SVN in a file named svn.rb and an associated table svns.
SCM::SVN looks best to me. Rails is full of classes like ERB, ORM and OMFGIMATEAPOT. And that's not to mention things like JSONSerializer. Ruby's source has a bunch of acronyms, too. The most obvious example to me is YAML. The standard as I've seen it is to upcase letters for CamelCase but generally not to downcase them (although Rails has opinions on model names).
If you have grep and the source code you can see plenty of examples with something like
grep -r 'class [A-Z]\{3,\}' <path/to/source>
# or, if you only want acronyms and nothing like YAMLColumn:
grep -rw 'class [A-Z]\{3,\}' <path/to/source>
I think that SCM::SVN looks better (aesthetically), and I've seen libraries that use the same convention. It's really just a matter of what you think reads better.
(However, note that if you are building a Rails project, and want this module to be autoloaded from the /lib directory, you may have to use Scm::Svn.)
When I see any Ruby method printed in text, it usually appears as:
Class#method
or
#method
Now, I would use:
Class.method
Why are all Ruby methods preceded by a pound sign? Is there any reason for it?
Note that the convention is:
Class#method
rather than
object#method
In code you would have object.method, if object was an instance of class. The # convention is not used in code.
From the RDoc documentation:
Use :: for describing class methods, # for describing instance methods, and use . for example code.
The # notation is used to refer to the canonical instance method, like String#upcase. The . notation is used to refer to the method of a particular instance, like mystring.upcase. The distinction is made to not imply that a class method 'upcase' exists.
I just realized that none of the other answers touch the most trivial aspect of the question: why the # sign?
I have two theories:
It might come from Smalltalk, where symbols are written #sym (instead of :sym) as they are in Ruby. So, if you want to refer to a Method object (as opposed to calling a method), then you would call something like Array >> #new. (The >> is itself a method that returns the method passed to it. So, in Ruby that would be Array.method :new.) In Smalltalk documentation, methods are generally referred to as Class>>method, but in Ruby Class:method would have made more sense, except that it is easily confused with Class::method. Therefore, Class#method was chosen.
My other theory is that it simply was chosen because # is the comment character in Ruby.
A definitive answer can only be given by whoever invented that convention. If it was invented for the Programming Ruby book, that would be either Dave Thomas or Andy Hunt, but I kind of doubt that. The book came out in 2001, Ruby started in 1993, how were they referring to methods before then?
From the rdoc docs (emphasis mine):
Names of classes, source files, and
any method names containing an
underscore or preceded by a hash
character are automatically
hyperlinked from comment text to their
description.
The hash notation was introduced "Programming Ruby - The Pragmatic Programmer's Guide" first published in December 2000.
The "Preface" contains "Notational Conventions":
Within the text, Fred#doIt is a reference to an instance method (doIt) of class Fred, while Fred.new [In some other Ruby documentation, you may see class methods written as Fred::new. This is perfectly valid Ruby syntax; we just happen to feel that Fred.new is less distracting to read.] is a class method, and Fred::EOF is a class constant.
This is clarified in the 2nd edition, published in October 2004:
Within the text, Fred#do_something is a reference to an instance method (in this case do_something) of class Fred, Fred.new is a class method, and Fred::EOF is a class constant. The decision to use a hash character to indicate instance methods was a tough one: it isn’t valid Ruby syntax, but we thought that it was important to differentiate between the instance and class methods of a particular class. When you see us write File.read, you know we’re talking about the class method read. When instead we write File#read, we’re referring to the instance method read.
Ruby itself uses this notation:
> rvm use 1.9.3
Using ruby-1.9.3-p551
> Object.instance_method(:initialize)
=> #<UnboundMethod: Object(BasicObject)#initialize>
It was introduced and formalised by Matz in February 2002:
commit 8210c254bee19294af67bcee0e8f5e02ebb39a60
Author: matz <matz#b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Tue Feb 5 07:56:31 2002 +0000
* io.c (fptr_finalize): should raise error when fclose fails.
* eval.c (method_inspect): proper output format to distinguish
methods and singleton methods.
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk#2046 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
All the answers above you list are correct. The one thing I would add is that the documentation style you said you would perfer
Class.method
would be easily confused with class methods. Since you can call class methods in ruby using the above syntax:
class Foo
def self.say_hi
puts "hi"
end
end
Foo.say_hi # => prints "hi"
This was mentioned in the JS version of this question, but it seems likely this nomenclature came from JavaDoc where the hash mark is translated directly into an on-page reference, e.g. href="Component.html#getComponentAt(int, int)"
heff's answer (which I can't comment on due to lack of reputation), that Ruby followed JavaDoc's example, is the best guess in my view. The JavaDoc designers needed or wanted a way to distinguish package qualifiers (which they used the dot for) from class qualifiers (which they used the hash for). JavaDoc's #see and #link tags syntax looks like this:
#see package.class#member [optional label]
{#link package.class#member [optional label]}
See the documentation of JavaDoc's package.class variant of the #see tag and the documentation of JavaDoc's #link tag, which heff already pointed to.
In JavaDoc, the package name can often be omitted, so that only the Class#member part remains, which looks equally strange as in Ruby, because Java code uses the Class.member syntax,
just as Ruby does.
It would be interesting to find out why the JavaDoc designers needed the differing syntax, while the Java compiler does fine with dots for both purposes.