https://github.com/umputun/unfuck-ai-comments
converts all comments inside go functions to lowercase
https://github.com/umputun/unfuck-ai-comments
ai-tools comments formatter golang
Last synced: 26 days ago
JSON representation
converts all comments inside go functions to lowercase
- Host: GitHub
- URL: https://github.com/umputun/unfuck-ai-comments
- Owner: umputun
- License: mit
- Created: 2025-02-27T22:23:49.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-07-05T18:20:44.000Z (3 months ago)
- Last Synced: 2025-07-05T19:34:05.898Z (3 months ago)
- Topics: ai-tools, comments, formatter, golang
- Language: Go
- Homepage:
- Size: 1.63 MB
- Stars: 10
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# unfuck-ai-comments [](https://github.com/umputun/unfuck-ai-comments/actions/workflows/ci.yml) [](https://coveralls.io/github/umputun/unfuck-ai-comments?branch=master)
A simple CLI tool that converts all comments inside Go functions and structs to lowercase while preserving comments for packages and function definitions, as well as special indicator comments like TODO and FIXME. This makes comments in code consistent and easier to read.
## Motivation
Modern AI coding assistants like GitHub Copilot, Claude, and ChatGPT have become invaluable tools for many developers. However, they often generate code with inconsistent comment styling, including:
- ALL UPPERCASE comments for emphasis
- Initial Uppercase Words for pseudo-titles
- Mixed Case comments that Don't Follow conventions
For example:
```go
func ProcessData(data []byte) error {
// CHECK FOR EMPTY INPUT
if len(data) == 0 {
return errors.New("empty data")
}
// Important: Validate Data Before Processing
if !isValid(data) {
return errors.New("invalid data format")
}
// This Function handles Multiple Formats
switch determineFormat(data) {
// Process Each Format differently
// ...
}
}
```
This inconsistent capitalization clashes with Go's conventional style where in-function comments typically use lowercase sentences. While these AI-generated comments are helpful in the moment, they create visual noise and inconsistency in codebases.
This tool automatically normalizes comments to match standard Go code conventions, ensuring your codebase maintains a consistent style regardless of whether the code was written by a human or generated by AI.
The tool is smart enough to preserve proper documentation comments (package comments and function documentation) while only modifying comments inside function bodies.
## Installation
```
go install github.com/umputun/unfuck-ai-comments@latest
```
Other install methods
**Install from homebrew (macOS)**
```bash
brew tap umputun/apps
brew install umputun/apps/unfuck-ai-comments
```
**Install from deb package (Ubuntu/Debian)**
1. Download the latest version of the package by running: `wget https://github.com/umputun/unfuck-ai-comments/releases/download//unfuck-ai-comments__linux_.deb` (replace `` and `` with the actual values).
2. Install the package by running: `sudo dpkg -i unfuck-ai-comments__linux_.deb`
Example for the version 0.1.1 and amd64 architecture:
```bash
wget https://github.com/umputun/unfuck-ai-comments/releases/download/v0.1.1/unfuck-ai-comments_v0.1.1_linux_.deb
sudo dpkg -i unfuck-ai-comments_v0.1.1_linux_.deb
```
**Install from rpm package (CentOS/RHEL/Fedora/AWS Linux)**
```bash
wget https://github.com/umputun/unfuck-ai-comments/releases/download/v/unfuck-ai-comments_v_linux_.rpm
sudo rpm -i unfuck-ai-comments_v_linux_.rpm
```
**Install from apk package (Alpine)**
```bash
wget https://github.com/umputun/unfuck-ai-comments/releases/download//unfuck-ai-comments__linux_.apk
sudo apk add unfuck-ai-comments__linux_.apk
```
## Usage
The tool uses subcommands for different operations:
```
unfuck-ai-comments [options] [file-patterns...]
```
Available commands:
- `run`: Process files in place (default)
- `diff`: Show diff without modifying files
- `print`: Print processed content to stdout
Process all .go files in the current directory:
```
unfuck-ai-comments run
```
Process a specific file:
```
unfuck-ai-comments run file.go
```
Process all .go files recursively:
```
unfuck-ai-comments run ./...
```
Show what would be changed without modifying files:
```
unfuck-ai-comments diff ./...
```
## Options
- `--dry`: Don't modify files, just show what would be changed (shortcut for diff command)
- `--title`: Convert only the first character to lowercase, keep the rest unchanged (default mode)
- In this mode, all-uppercase abbreviations and camelCase/PascalCase identifiers are preserved
- `--full`: Convert entire comment to lowercase, not just the first character
- In this mode, camelCase/PascalCase identifiers are still preserved
- `--fmt`: Format the output using "go fmt"
- `--skip`: Skip specified files or directories (can be used multiple times)
- `--backup`: Create .bak backup files for any files that are modified
- `-v` or `--version`: Display version information
- `--help` or `-h`: Show usage information
## Examples
Show diff for all Go files in the current directory:
```
unfuck-ai-comments diff .
```
Print the modified content to stdout:
```
unfuck-ai-comments print file.go
```
Process all Go files recursively and modify them:
```
unfuck-ai-comments run ./...
```
Use full lowercase mode (convert entire comment to lowercase) on all Go files:
```
unfuck-ai-comments --full run ./...
```
Skip specific files or directories:
```
unfuck-ai-comments run ./... --skip vendor --skip "*_test.go"
```
Create backup (.bak) files when modifying:
```
unfuck-ai-comments run --backup ./...
```
## How it works
The tool uses Go's AST (Abstract Syntax Tree) parser to intelligently identify and process comments based on their context in the code. Here's a detailed explanation of how it works:
### File Processing and Analysis
1. **AST Parsing**: The tool uses Go's `parser` package to create an AST representation of each Go file, which allows it to understand the structure of the code and the context of each comment.
2. **Skip Mechanisms**:
- Automatically skips the `vendor/` and `testdata/` directories (common in Go projects)
- Skips generated files that contain the standard Go comment marker `// Code generated`
- Respects custom skip patterns specified with the `--skip` flag
3. **Recursive Processing**: When using `./...` pattern, the tool recursively walks through directories to find all `.go` files.
### Intelligent Comment Detection
The tool carefully distinguishes between different types of comments:
1. **Documentation Comments**: Comments outside functions that document packages, types, or exported identifiers are preserved in their original form.
2. **Inside-Function Comments**: The tool identifies comments that appear:
- Inside function bodies
- Inside struct field definitions
- Inside variable and constant blocks
- Inside control structures (if/for/switch)
3. **Identifier Documentation**: The tool preserves comments that follow the standard Go pattern of "IdentifierName is..." which are typically used for documenting constants, variables, and other declarations.
### Comment Modification Logic
When processing comments, the tool applies several intelligent rules:
1. **Title Case Mode** (default):
- Only converts the first character of a comment to lowercase
- Preserves all-uppercase abbreviations like "AI", "CPU", "HTTP"
- Ensures the first word isn't a camelCase/PascalCase identifier
- Checks if the first word is entirely uppercase (at least 2 characters) and preserves it if true
2. **Full Lowercase Mode**:
- Converts the entire comment to lowercase
- Intelligently preserves camelCase and PascalCase identifiers to maintain code readability
3. **Technical Comments Handling**:
- Handles double comment format like `nolint:gosec // using math/rand is acceptable for tests`
- Properly processes the actual comment part while preserving directives
### Special Indicator Preservation
Comments that begin with special indicators are preserved completely unchanged:
- `TODO`, `FIXME`, `HACK`, `XXX`, `NOTE`, `BUG`, `IDEA`
- `OPTIMIZE`, `REVIEW`, `TEMP`, `DEBUG`, `NB`
- `WARNING`, `DEPRECATED`, `NOTICE`
These indicators are important for marking code that needs attention and are intentionally left in their original form.
### Identifier Preservation
The tool uses sophisticated detection for camelCase and PascalCase identifiers:
- PascalCase detection requires an uppercase first letter, at least one more uppercase letter followed by lowercase, and no consecutive uppercase letters
- CamelCase detection looks for an uppercase letter that isn't the first character
All such identifiers within comments are preserved in their original form, ensuring that references to code elements remain clear and recognizable.
### Output Modes
The tool supports three different output modes:
1. **In-place Mode** (`run`): Directly modifies the source files, with optional backups (when `--backup` is used)
2. **Diff Mode** (`diff` or `--dry`): Shows a colorized diff of changes without modifying files, using red for removed lines and green for added lines
3. **Print Mode** (`print`): Outputs the processed content to stdout without changing the original files
When enabled with the `--fmt` flag, all output is also processed through `gofmt` to ensure consistent formatting.