code-analysis

AbeJitsu 的头像作者 AbeJitsu

检查代码是否可以被非开发人员阅读 - 清晰的名称、简单的英语注释、没有行话

📖 中文导读:检查代码是否可以被非开发人员阅读 - 清晰的名称、简单的英语注释、没有行话 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: code-analysis description: Check if code is readable by non-developers - clear names, plain English comments, no jargon version: 1.0.0 author: abereyes triggers: - "check readability" - "is this code clear" - "can non-devs understand"

Code Readability Checker

Analyzes code to ensure non-developers (managers, stakeholders, new team members) can understand it.

What It Checks

  • Clear naming: No cryptic abbreviations (usr_tkn → userToken)
  • Plain comments: Everyday language, not technical jargon
  • Documentation: What/Why/How for major sections
  • Comment ratio: At least 20% of lines should be comments

Usage

python3 analyze.py --path your-file.py --strictness lenient

Example

Bad Code (score: 71/100):

def proc(usr, tkn):
    tmp = usr + tkn
    return tmp * 2

Issues: Cryptic names, no comments, unclear purpose.

Good Code (score: 95/100):

def process_user_authentication(username, auth_token):
    """Validate user credentials and return auth score"""
    combined_credential = username + auth_token
    return combined_credential * 2

Known Issues

  • May flag false positives in documentation files
  • Works best on actual production code
  • Use --strictness lenient to reduce noise