IdeaWell

Project ideas from Hacker News discussions.

Maybe comments should explain 'what' (2017)

Original Article

Hacker News Discussion

📝 Discussion Summary (Click to expand)

1. Critique of Uncle Bob's "Clean Code" Style

Users widely reject extreme short functions and over-extraction as navigationally frustrating and readability-killing. "I feel like no one serious uses the uncle Bob style of programming anymore (where each line is extracted into its own method)... It's a constant frustration of pressing the 'go to definition' key over and over" (awesan). "There's a lot of Go people who enjoy that kind of thing (flashback to when I was looking at an interface calling an interface... through 8 files)" (zimpenfish). Contrasts with books like A Philosophy of Software Design praised over Clean Code (WillAdams).

2. "Why" Comments Over "What" Comments

Consensus favors comments explaining intent/business rules ("why") rather than mechanics ("what"), which should be self-evident via names/structure. "The 'why' is the part of the explanation that can't be deduced from the code" (Scarblac). "Comments should answer the question why you are not using some kind of hash set" (Bootvis). Risks of "what" comments: "they spread misinformation and confusion... worse than no comments at all" (tangotaylor). Exceptions for domain knowledge or tricks (jackfranklyn).

3. Prioritize Locality and Inline Readability

Keep related code together for mental flow over abstraction/reuse dogma. "If a lot of operations are supposed to happen in a sequential fashion, their code should follow sequentially" (jffhn, quoting Carmack). "I'd rather have everything I need in front of my eyes... rather than have it all over the place" (ekjhgkejhgk). Suggestions: inline expansions in IDEs (falcor84), decomposed constants (tetha), tests as docs (peheje).

🚀 Project Ideas

Recursive Inline Code Viewer

Summary

  • VS Code extension that shows a hover preview of recursively inlined code for small functions/methods (e.g., <20 lines), collapsing the call chain into a single readable block.
  • Solves navigation hell from "Uncle Bob" style code by letting developers see sequential logic without endless "go to definition" jumps.

Details

Key Value
Target Audience Developers debugging/refactoring fragmented Java/Go/C# codebases
Core Feature Hover or click on a function call to display inlined view with original source links; toggleable filters for max depth/lines
Tech Stack VS Code Extension API, Tree-sitter for parsing, TypeScript
Difficulty Medium
Monetization Hobby

Notes

  • Directly addresses awesan's "constant frustration of pressing the 'go to definition' key over and over" and falcor84's "IDE 'lens' extension that would automatically show you a recursively inlined version".
  • HN would love the practical utility for real-world bug fixes; sparks discussions on IDE innovations like Haskell's easy navigation (xlii).

Method Merger Refactor Tool

Summary

  • CLI/linter tool that detects over-extracted "tiny method" chains (e.g., sequential calls >5 deep, <5 lines each) and suggests/proposes merges into readable blocks.
  • Fixes readability loss from extreme DRY/abstraction without losing modularity, generating safe PR diffs.

Details

Key Value
Target Audience Teams/maintainers of legacy Java/C#/Go code enforcing Clean Code dogma
Core Feature Analyzes call graphs, scores fragmentation (e.g., nav cost), auto-generates merged versions with tests preserved
Tech Stack Tree-sitter/Semgrep for analysis, Rust CLI, GitHub Action integration
Difficulty High
Monetization Revenue-ready: Freemium GitHub App ($10/mo pro)

Notes

  • Targets zimpenfish's "interface calling an interface... through 8 files" and JanNash's "immensely over-abstracted framework that bit me... for years"; echoes mannykannot's "reuse... made available in principle than found useful in practice".
  • High utility for PRs; HN debates on automation vs. judgment, potential for viral OSS adoption.

LLM-Powered Comment Validator

Summary

  • IDE plugin/service that uses LLMs to audit comments: flags outdated/misleading "what" comments, suggests "why" rewrites, validates against code execution/tests.
  • Prevents "comments lie" rot and business logic confusion, ensuring docs stay accurate amid changes.

Details

Key Value
Target Audience Developers in domain-heavy code (accounting, data science) needing reliable context
Core Feature Scan file → LLM infers code behavior → compare to comments; auto-fix "what" to names/tests, enrich "why" with business rules
Tech Stack LSP/VS Code/JetBrains plugin, OpenAI/Claude API, Pytest/JUnit integration
Difficulty Medium
Monetization Revenue-ready: SaaS ($5/mo per user)

Notes

  • Solves jbreckmckye's algorithmic needs, jackfranklyn's "business rules impenetrable otherwise", and Scarblac's "comments... going out of sync"; counters peheje's "comment becomes a liability".
  • HN appreciates LLM practicality (akabalanza: "LLMs will make these conversations obsolete"); fosters talks on AI dev tools reliability.

Read Later