DOCSP-45187: Update #98
Conversation
✅ Deploy Preview for docs-ruby ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
| require 'bundler/inline' | ||
| gemfile do | ||
| source 'https://rubygems.org' | ||
| gem 'mongo' | ||
| end |
There was a problem hiding this comment.
Q: have we gotten any guidance from the ruby team about bundler vs. just require 'mongo'?
There was a problem hiding this comment.
Not sure – I'm going off the Quick Start (which shows the use of bundler), which I assumed had been tech reviewed.
There was a problem hiding this comment.
Using bundler definitely describes a more complete picture, but for example scripts I think it's sufficient to just require 'mongo', personally.
| documents in a MongoDB collection by using the ``update_one`` and | ||
| ``update_many`` methods. |
There was a problem hiding this comment.
Q: most of our docs include parentheses after a method name; is there something different about ruby?
There was a problem hiding this comment.
I asked Nora about this – it seems like current Ruby documentation avoids using parentheses. The language in general seems more relaxed about using parentheses in code.
There was a problem hiding this comment.
Parentheses are largely optional in Ruby, as long as the meaning is unambiguous. By convention, parentheses are almost always omitted when a method call has no parameters (e.g file.close). Otherwise, Rubyists often omit parentheses when there is only a single literal argument (e.g. puts "hello") or with keyword arguments (e.g. foo a: 1, b: "two"). It becomes a stylistic concern at that point.
Asking MongoGPT about it, the all-knowing AI suggests the following:
In Ruby, omitting parentheses for method arguments is common, especially in certain contexts where it enhances readability and maintains a more natural syntax. Here are some conventions and guidelines that developers often follow when deciding whether to omit parentheses:
-
DSLs (Domain-Specific Languages): When designing or using DSLs, parentheses are often omitted to create a syntax that reads more like a natural language. This is common in frameworks like Rails, particularly in routing and validation declarations.
-
Control Structures: For built-in Ruby control structures such as
if,while,until, andcase, parentheses are typically omitted around their conditions to improve readability and maintain a cleaner syntax. -
Short Methods: When calling methods that take no arguments or only a single simple argument, it is common to omit parentheses to streamline the code. For example:
puts "Hello, world"
-
Internal DSLs or Configure Blocks: In configurations or setup blocks (e.g., Rake tasks, ActiveRecord scopes), omitting parentheses can make the code easier to follow and more domain-centric.
-
Chaining Methods: When method calls are chained, parentheses are usually omitted for the first method call if it takes a single argument, leading to a more fluid syntax.
-
Readability: Parentheses can be omitted when they enhance readability by removing unnecessary clutter, especially in expressions that are clearly understood without them.
However, there are also scenarios where including parentheses is preferred:
- Ambiguity: If omitting parentheses leads to ambiguity or confusion about the order of operations, it is better to include them.
- Multi-Argument Methods: When a method takes multiple arguments, especially with complex expressions, using parentheses can make the argument list clearer.
- Precedence Issues: In expressions with complex operator precedence, including parentheses can clarify the intended order of operations.
- Method Definitions: When defining methods, it's common to use parentheses for the argument list to clearly specify the parameters, even though it is optional.
Ultimately, the decision to omit parentheses often comes down to personal or team styling preferences, but developers should aim for consistency and clarity in their code.
source/write/update.txt
Outdated
| For more information, see the :manual:`hint statement </reference/command/update/#std-label-update-command-hint>` | ||
| in the {+mdb-server+} manual. | ||
|
|
||
| * - ``let`` | ||
| - | Provides a map of parameter names and values to set top-level | ||
| - | A map of parameter names and values to set top-level |
There was a problem hiding this comment.
| - | A map of parameter names and values to set top-level | |
| - | Map of parameter names and values to set top-level |
source/write/update.txt
Outdated
|
|
||
| * - ``collation`` | ||
| - | Specifies the kind of language collation to use when sorting | ||
| - | The kind of language collation to use when sorting |
There was a problem hiding this comment.
| - | The kind of language collation to use when sorting | |
| - | Language collation to use when sorting |
source/write/update.txt
Outdated
| doesn't match any existing documents. | ||
| Because the ``upsert`` option is set to ``true``, if the query filter | ||
| doesn't match any existing documents, the driver inserts a new document that | ||
| has the fields and values in the filter and update documents. |
There was a problem hiding this comment.
S:
| has the fields and values in the filter and update documents. | |
| contains the fields and values in the filter and update documents. |
Pull Request Info
PR Reviewing Guidelines
JIRA - https://jira.mongodb.org/browse/DOCSP-45187
Staging Links
Self-Review Checklist