aboutsummaryrefslogtreecommitdiffstats
path: root/guides/source/api_documentation_guidelines.md
diff options
context:
space:
mode:
authorXavier Noria <fxn@hashref.com>2014-01-26 22:10:05 +0100
committerZachary Scott <zachary@zacharyscott.net>2014-02-09 12:29:45 +0100
commit7afd92e60b38b34404a38592d6e3e652c1623b6a (patch)
tree43446cba870d8b4957ab13e00e411cadb0fc5b5d /guides/source/api_documentation_guidelines.md
parent605c81b9de24535993046d9a50408ad98feee9c0 (diff)
downloadrails-7afd92e60b38b34404a38592d6e3e652c1623b6a.tar.gz
rails-7afd92e60b38b34404a38592d6e3e652c1623b6a.tar.bz2
rails-7afd92e60b38b34404a38592d6e3e652c1623b6a.zip
adds a section about booleans in the API guidelines [ci skip]
Diffstat (limited to 'guides/source/api_documentation_guidelines.md')
-rw-r--r--guides/source/api_documentation_guidelines.md47
1 files changed, 47 insertions, 0 deletions
diff --git a/guides/source/api_documentation_guidelines.md b/guides/source/api_documentation_guidelines.md
index 311cc23cf0..622d57a943 100644
--- a/guides/source/api_documentation_guidelines.md
+++ b/guides/source/api_documentation_guidelines.md
@@ -128,6 +128,53 @@ On the other hand, regular comments do not use an arrow:
# polymorphic_url(record) # same as comment_url(record)
```
+Booleans
+--------
+
+In predicates and flags prefer documenting boolean semantics over exact values.
+
+When "true" or "false" are used as defined in Ruby use regular font. The
+singletons `true` and `false` need fixed-width font. Please avoid terms like
+"truthy", Ruby defines what is true and false in the language, and thus those
+words have a technical meaning and need no substitutes.
+
+As a rule of thumb, do not document singletons unless absolutely necessary. That
+prevents artificial constructs like `!!` or ternaries, allows refactors, and the
+code does not need to rely on the exact values returned by methods being called
+in the implementation.
+
+For example:
+
+```markdown
+`config.action_mailer.perform_deliveries` specifies whether mail will actually be delivered and is true by default
+```
+
+the user does not need to know which is the actual default value of the flag,
+and so we only document its boolean semantics.
+
+An example with a predicate:
+
+```ruby
+# Returns true if the collection is empty.
+#
+# If the collection has been loaded
+# it is equivalent to <tt>collection.size.zero?</tt>. If the
+# collection has not been loaded, it is equivalent to
+# <tt>collection.exists?</tt>. If the collection has not already been
+# loaded and you are going to fetch the records anyway it is better to
+# check <tt>collection.length.zero?</tt>.
+def empty?
+ if loaded?
+ size.zero?
+ else
+ @target.blank? && !scope.exists?
+ end
+end
+```
+
+The API is careful not to commit to any particular value, the predicate has
+predicate semantics, that's enough.
+
Filenames
---------