Resources Used Lints

Lint rules for documentation of resources used in CSE 340.

Overview

This package provides lint rules to ensure students properly document their use of external resources and AI tools in their code comments, following a format similar to Flutter's TODO comment style.

Comment Formats

CONSULTED Comments

Document external resources consulted:

// CONSULTED(URL_OF_RESOURCE): Explanation of how the resource was used

Example:

// CONSULTED(https://stackoverflow.com/questions/12345): Found algorithm for sorting implementation

AI_PROMPT Comments

Document prompts given to AI tools:

// AI_PROMPT(GENAI_TOOL_NAME): The prompt text provided to the AI

Example:

// AI_PROMPT(ChatGPT): Please help me implement a binary search function in Dart

AI_RESPONSE Comments

Document responses received from AI tools:

// AI_RESPONSE(GENAI_TOOL_NAME): The output received from the AI
//   Additional lines of response can continue
//   with proper indentation

Example:

// AI_RESPONSE(ChatGPT): Here's a binary search implementation:
//   int binarySearch(List<int> arr, int target) {
//     int left = 0, right = arr.length - 1;
//     // ... rest of implementation
//   }

AI_OTHER Comments

Document other uses of AI tools:

// AI_OTHER(GENAI_TOOL_NAME): Description of other AI assistance received

Example:

// AI_OTHER(GitHub Copilot): Used autocomplete suggestions for variable naming

REFLECTION Comments

Document learning and modifications made:

// REFLECTION: Student reflection on what was learned and any changes made

Example:

// REFLECTION: The AI solution needed modification to handle edge cases properly. I learned about the importance of input validation.

Lint Rules

Format Rules

• consulted_format: Ensures CONSULTED comments follow the proper format
• ai_prompt_format: Ensures AI_PROMPT comments follow the proper format
• ai_response_format: Ensures AI_RESPONSE comments follow the proper format
• ai_other_format: Ensures AI_OTHER comments follow the proper format
• reflection_format: Ensures REFLECTION comments follow the proper format

Relationship Rules

• ai_prompt_response_pair: Ensures every AI_PROMPT is followed by an AI_RESPONSE with the same tool name
• reflection_required: Ensures all CONSULTED and AI_* comments are followed by REFLECTION comments

Usage

1. Add this package as a dev dependency in your pubspec.yaml:

dev_dependencies:
  resources_used_lints:
  custom_lint: ^0.8.1

2. Create or update your analysis_options.yaml:

analyzer:
  plugins:
    - custom_lint

custom_lint:
  rules:
    # Resource documentation format rules
    - consulted_format
    - ai_prompt_format
    - ai_response_format
    - ai_other_format
    - reflection_format

    # Relationship validation rules
    - ai_prompt_response_pair
    - reflection_required

3. Run the linter:

dart run custom_lint

Example Valid Comment Sequence

// CONSULTED(https://dart.dev/guides/language/language-tour): Learned about async/await
// REFLECTION: Understanding async programming helped me write better concurrent code

// AI_PROMPT(ChatGPT): How do I implement error handling in async functions?
// AI_RESPONSE(ChatGPT): Use try-catch blocks around await expressions and handle specific exception types
// REFLECTION: I had to add additional null checks that the AI didn't mention

// AI_OTHER(GitHub Copilot): Used for auto-completing import statements
// REFLECTION: Copilot suggestions saved time but I verified each import was actually needed