feat: Update CONVENTIONS.md with comprehensive guidelines

bash-my-aws · Oct 2, 2024 · be707a0 · be707a0
1 parent 16caff0
commit be707a0
Showing 1 changed file with 32 additions and 6 deletions.
diff --git a/CONVENTIONS.md b/CONVENTIONS.md
@@ -7,6 +7,7 @@ This document outlines the coding conventions used in our project, particularly
 ### Function Naming
 - Use lowercase with hyphens for function names (e.g., `vpc-subnets`, `vpc-route-tables`).
 - Function names should be descriptive of their purpose.
+- For AWS resource-related functions, use the format `resource-type-action` (e.g., `vpc-igw`, `vpc-nat-gateways`).
 
 ### Comments
 - Use `#` for single-line comments.
@@ -21,6 +22,8 @@ This document outlines the coding conventions used in our project, particularly
 ### Output Formatting
 - Use `columnise` (a custom function) to format output into columns.
 - Sort output when appropriate (e.g., `sort -k 5`).
+- For listing functions, output should typically include resource IDs and names.
+- Include 'NO_NAME' for resources without a Name tag.
 
 ### Error Handling
 - Check for required arguments using `[[ -z "$vpc_ids" ]] && __bma_usage "vpc-id [vpc-id]" && return 1`.
@@ -34,16 +37,39 @@ This document outlines the coding conventions used in our project, particularly
 
 ### Input Handling
 - Use `skim-stdin` (a custom function) to handle both piped input and arguments.
+- Allow functions to accept input from both command-line arguments and piped input.
 
-## AWS Resource Naming
-- Use the format `resource-type-action` for function names that interact with specific AWS resources (e.g., `vpc-igw`, `vpc-nat-gateways`).
+### Function Structure
+- Start with input validation and error handling.
+- Use local variables to store intermediate results.
+- Prefer using AWS CLI with appropriate filters and queries over post-processing with grep/awk when possible.
 
-## Output Conventions
-- For listing functions, output should typically include resource IDs and names.
-- Include 'NO_NAME' for resources without a Name tag.
+## AWS Resource Conventions
+
+### Resource Listing
+- Functions that list resources should follow a consistent output format.
+- Include relevant identifiers (e.g., VPC ID, Subnet ID) in the output.
+- Include resource names when available, use 'NO_NAME' for unnamed resources.
+
+### Resource Manipulation
+- Functions that modify resources should include safety checks.
+- For destructive actions, include comments or echo statements explaining the process.
 
 ## Security Considerations
 - Be cautious with functions that perform destructive actions (e.g., `vpc-default-delete`).
 - Include safety checks before performing destructive actions.
+- When dealing with sensitive information, use appropriate AWS CLI options to handle credentials securely.
+
+## Utility Functions
+- Create and use utility functions for common operations (e.g., `__bma_read_filters`, `__bma_usage`).
+- Prefix internal utility functions with double underscores (e.g., `__bma_error`).
+
+## Documentation
+- Include a brief description of each function's purpose in comments.
+- For complex functions or those with multiple options, include usage examples in the comments.
+
+## Consistency
+- Maintain consistent indentation (prefer 2 spaces).
+- Use consistent naming conventions across all functions.
 
-These conventions are derived from the observed patterns in the lib/vpc-functions file. They should be followed when contributing new functions or modifying existing ones to maintain consistency across the project.
+These conventions are derived from the observed patterns in the project files. They should be followed when contributing new functions or modifying existing ones to maintain consistency across the project.