-
Notifications
You must be signed in to change notification settings - Fork 5.6k
Ruby code example standards
ford prior edited this page Jul 12, 2024
·
6 revisions
This document summarizes important points for writing and reviewing code examples written for the AWS Ruby SDK (v3). For more information on tools and standards, refer to the complete list in the TCX Code Examples Standards.
-
Top-level
/ruby
dir- Should contain a
Gemfile
that lists all dependencies.
- Should contain a
-
Service Folders:
- Should include a wrapper class, a
spec
folder, and any scenarios in their own files.
- Should include a wrapper class, a
-
Scenario Files:
- Should include shared functionality such as handling user input.
- Should include an
initialize
function that takes the service wrapper as a parameter. - Should include a
run_scenario
method that runs the scenario. - Should begin with a descriptive comment block describing the steps of the scenario.
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
=begin
Purpose
Shows how to use the AWS SDK for Ruby (v3) with AWS Glue to do the following:
* Create a crawler.
* Run a crawler to output a database.
* Query the database.
* Create a job definition that runs an ETL script.
* Start a new job.
* View results from a successful job run.
* Delete job definition and crawler.
=end
require 'aws-sdk-glue'
require 'aws-sdk-iam'
require 'aws-sdk-s3'
require 'logger'
require_relative('glue_wrapper')
class GlueScenario
# Runs an interactive scenario that shows how to get started using AWS Glue.
def initialize(glue_wrapper)
@glue_wrapper = glue_wrapper
end
def run_scenario
# Scenario steps go here.
end
end
if $PROGRAM_NAME == __FILE__
scenario = GlueScenario.new(GlueWrapper.new(Aws::Glue::Client.new, Logger.new($stdout)))
scenario.run_scenario
end
-
Wrapper Methods:
- Should provide additional context when calling service actions. For example, specify certain parameters and return true or false. Do not use Request/Response classes directly as the parameter and response types.
- Should include a
from_client
method that initializes the service client. This client should be reused throughout the wrapper class. - Should include a class declaration snippet to include in the Code Library metadata.
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
require 'aws-sdk-glue'
require 'logger'
# snippet-start:[ruby.example_code.glue.GlueWrapper.class]
# snippet-start:[ruby.example_code.glue.GlueWrapper.decl]
class GlueWrapper
# Encapsulates AWS Glue actions.
def initialize(glue_client, logger)
@glue_client = glue_client
@logger = logger
end
# snippet-start:[ruby.example_code.glue.GetCrawler]
# Retrieves information about a specific crawler.
#
# @param name [String] The name of the crawler to retrieve information about.
# @return [Aws::Glue::Types::Crawler, nil] The crawler object if found, or nil if not found.
def get_crawler(name)
@glue_client.get_crawler(name: name)
rescue Aws::Glue::Errors::EntityNotFoundException
@logger.info("Crawler #{name} doesn't exist.")
false
rescue Aws::Glue::Errors::GlueException => e
@logger.error("Glue could not get crawler #{name}: \n#{e.message}")
raise
end
# snippet-end:[ruby.example_code.glue.GetCrawler]
# Additional wrapper methods...
end
# snippet-end:[ruby.example_code.glue.GlueWrapper.class]
-
Comments:
- All classes and methods should include a descriptive comment block.
- All methods should include
@param
tag comments for each parameter and the method response.
# snippet-start:[ruby.example_code.glue.CreateCrawler]
# Creates a new crawler with the specified configuration.
#
# @param name [String] The name of the crawler.
# @param role_arn [String] The ARN of the IAM role to be used by the crawler.
# @param db_name [String] The name of the database where the crawler stores its metadata.
# @param db_prefix [String] The prefix to be added to the names of tables that the crawler creates.
# @param s3_target [String] The S3 path that the crawler will crawl.
# @return [void]
def create_crawler(name, role_arn, db_name, db_prefix, s3_target)
@glue_client.create_crawler(
name: name,
role: role_arn,
database_name: db_name,
targets: {
s3_targets: [
{
path: s3_target
}
]
}
)
rescue Aws::Glue::Errors::GlueException => e
@logger.error("Glue could not create crawler: \n#{e.message}")
raise
end
# snippet-end:[ruby.example_code.glue.CreateCrawler]
-
Logging:
- Use the
Logger
class for logging rather thanputs
statements. - Set up a logger at the module level and use it within classes and functions.
- Use the
require 'logger'
@logger = Logger.new($stdout)
-
Error Handling:
- Use
begin
andrescue
blocks to handle potential errors gracefully. - Log error messages using the logger.
- Raise exceptions when appropriate after logging the error.
- Use
begin
# Code that might raise an error
rescue Aws::Errors::ServiceError => e
@logger.error("An error occurred: #{e.message}")
raise
end
-
Testing:
- All wrapper methods and scenario methods should have test coverage.
- Unit tests should use the established service method stubbing patterns for testing.
- Integration tests should be marked with
RSpec.describe
and include context and it blocks for individual tests.
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
require 'aws-sdk-glue'
require 'logger'
require 'yaml'
require_relative('../glue_wrapper')
RSpec.describe GlueWrapper, integ: true do
context 'GlueWrapper' do
resource_names = YAML.load_file('resource_names.yaml')
glue_client = Aws::Glue::Client.new
glue_service_role_arn = resource_names['glue_service_role_arn']
glue_bucket_name = resource_names['glue_bucket_name']
wrapper = GlueWrapper.new(glue_client, Logger.new($stdout))
it 'checks for crawler existence' do
crawler_name = 'test-crawler'
expect(wrapper.get_crawler(crawler_name)).to be_falsey
end
# Additional tests...
end
end
-
Metadata for Action Examples:
- Should contain at minimum the following snippets:
- A declaration snippet to show the service and class setup.
- A snippet to show the action itself within context.
- If more than one variation of the action is included, use descriptions in the metadata to explain the differences.
- Should contain at minimum the following snippets:
metadata:
- description: >
This example shows how to create a new crawler in AWS Glue.
snippet_tags:
- ruby.example_code.glue.GlueWrapper.decl
- ruby.example_code.glue.CreateCrawler
- description: >
This example shows how to get a specific crawler in AWS Glue.
snippet_tags:
- ruby.example_code.glue.GlueWrapper.decl
- ruby.example_code.glue.GetCrawler
A concise list of essential resources for Ruby standards:
Resource | Description |
---|---|
AWS SDK for Ruby V3 | Comprehensive guide on using AWS SDK for Ruby V3. |
AWS Code Examples for Ruby | Collection of code examples demonstrating AWS SDK for Ruby. |
The Ruby Style Guide | Community-driven Ruby coding style guide. |
Ruby on Rails Guides | Guides covering a wide range of Ruby on Rails topics. |
Ruby Documentation | Official documentation for the Ruby programming language. |
RubyMonk | Interactive platform offering tutorials and exercises for learning Ruby. |
Exercism Ruby Track | Coding exercises in Ruby with mentorship and community feedback. |
- About the AWS SDK Code Examples repo
- Code quality guidelines - testing and linting
- Code comment guidelines
- Sample files guidelines
- Cross-service example guidelines
- README templates
-
Code example standards
- General standards
- .NET code example standards
- C++ code example standards
- CLI/Bash code example standards
- Go code example standards
- Kotlin code example standards
- Java code example standards
- JavaScript code example standards
- PHP code example standards
- Python code example standards
- Swift code example standards
- SAP-ABAP code example standards
- Ruby code example standards
- Rust code example standards