跳到正文
cccskills
免费在 GitHub 公开

rseng-software-metrics

Covers measuring code health quantitatively: cyclomatic complexity, code duplication, coupling and cohesion, code churn, maintainability index, size conventions and documentation coverage - running radon, lizard, jscpd, interrogate and SonarQube-class tools, interpreting numbers against community conventions and the software's tier, wiring metric gates into CI, and avoiding metric gaming. Use when the user asks how healthy, complex or maintainable their code is, wants metrics or duplication measured, mentions cyclomatic complexity, churn, coupling or maintainability index, or when a quality assessment (rseng-quality-framework) needs the quantitative half. For style and linting see rseng-code-quality; for runtime performance measurement see rseng-performance-profiling.

中文简介正在准备中。当前显示原文说明。

fdiblen/rseng-agent-skills星标 24(GitHub 24 + cccskills 0)

实测评分 未实测

查看安装方法

包含的文件(2)

  • SKILL.md6.6 KB
  • references.md453 B

SKILL.md(原文)

安装前可以查看交给 AI 代理的指令内容。

Software metrics for research code

Quality talk stays opinion until something is measured. A cluster of the community research software quality indicators is explicitly quantitative - complexity, duplication, cohesion/coupling, churn, maintainability index, size and documentation coverage "within community conventions" - and all of it is measurable in minutes with free tools. The discipline is in the interpretation: metrics LOCATE problems, humans judge them; a number out of convention is a place to look, not a verdict. And Goodhart's law is the standing hazard - when a metric becomes a target, it stops measuring (the gaming section below is as important as the tools).

The metrics and what they actually indicate

  • Cyclomatic complexity (independent paths per function): high values mean hard-to-test, hard-to-reason code; each point is roughly one more test case needed (rseng-testing). Look at the per-function outliers, never the average.
  • Duplication ratio: copy-pasted blocks that must be fixed twice; research code's most common debt (the "second copy-paste" signal from rseng-software-design's extraction rule, made measurable).
  • Coupling and cohesion: how tangled modules are (CBO-style counts) and how single-purpose they are internally - the quantitative face of rseng-software-design's change-cost test.
  • Code churn (change frequency per file): files that change constantly are either active development or a design hotspot; churn x complexity is the best bug-risk locator in the set.
  • Maintainability index: a composite; useful for trend and worst-file ranking, meaningless as an absolute grade.
  • Size conventions (LOC per function/module): long functions correlate with everything bad; community conventions vary by language (rseng-language-guides).
  • Documentation coverage: fraction of public functions/classes with docstrings (interrogate-style) - the measurable slice of rseng-documentation, and an explicit quality indicator.

Measuring: the tool layer

  • Python: radon (complexity, maintainability index, raw metrics), interrogate (docstring coverage); lizard covers complexity across a dozen languages (C/C++, Java, JS, Fortran-adjacent stacks) with no setup.
  • Duplication: jscpd scans mixed-language repositories quickly.
  • Churn: git itself (git log --format= --name-only | sort | uniq -c) - no tool needed; join with complexity for the hotspot map.
  • Platform-scale: SonarQube-class services aggregate all of the above with history when a team wants dashboards; overkill for a single analysis repo (match the tier).

Run measurements read-only first and report: worst five functions by complexity, duplication clusters, hotspot files (churn x complexity), doc-coverage percentage - with file:line locations so every number is actionable.

Interpreting against conventions and tier

"Community conventions" is the catalog phrasing for a reason - absolute thresholds are folklore, but working defaults exist: complexity warnings commonly start around 10 per function, duplication tolerance a few percent, doc coverage expectations scale with audience. Calibrate by tier (rseng-quality-framework): analysis code earns attention only for egregious outliers; shared libraries justify gates; infrastructure justifies trend tracking. State the convention being applied and why - an unexplained threshold is just a different opinion.

Gates and trends in CI

  • Ratchet, do not ambush: set gates at the CURRENT values so metrics cannot regress, then tighten deliberately - a strict gate on a legacy codebase blocks all work and gets disabled within a week (the same start-where-you-are rule as rseng-fairguard's quality gates).
  • Fail on new debt only where possible (changed-files scope), and keep the full-repo numbers as a tracked report, not a blocker (rseng-ci-cd).
  • Trends beat snapshots: rising churn in a complex module is a refactoring signal (rseng-legacy-code, rseng-software-design) worth an issue, even when every absolute number still passes.

Metric gaming, named

Every metric can be satisfied without improving anything: splitting functions mechanically to duck a complexity gate, deleting docstring checks instead of writing docstrings, suppressing duplication detection with trivial edits. Flag the pattern when reviewing (rseng-pair-programming's pre-review pass), and keep metrics plural - a basket is harder to game than a single number. The metric serves the change-cost reality, never the reverse; when a metric and good judgment disagree, judgment wins and the exception gets a comment.

Working with this skill

This skill is source-independent: its authority is the tool documentation and the published indicator definitions linked below. It supplies the quantitative half of rseng-quality-framework assessments; rseng-code-quality owns style and linting, rseng-performance-profiling owns runtime measurement.

Learn more (verified):

<!-- related-skills:begin -->

Related skills

Check whether any of these applies before moving on:

  • rseng-community-metrics - project-level counterpart to code metrics
  • rseng-documentation - doc-coverage is its measurable slice
  • rseng-legacy-code - hotspot map targets refactoring
  • rseng-maintenance-sustainability - trend tracking signals sustainability risk
  • rseng-quality-framework - supplies the quantitative half of assessments
  • rseng-software-design - coupling numbers test the design
<!-- related-skills:end -->

评价

还没有评价。欢迎分享你的使用感受。

评论

无需登录即可发表。欢迎分享使用感受、提问,或说明在哪些环境下无法运行。

还没有评论。来写第一条吧。

提交后会立即公开。请勿填写邮箱、电话等个人信息。URL 最多 2 个。

0 / 1000 字

此表单受 reCAPTCHA 保护,适用 Google 的隐私权政策和服务条款。

同一仓库的技能

Covers operating AI coding agents securely: auditing whether the agent runs sandboxed, permission and dangerous-command configuration, containerized environments, secrets kept out of context, network egress and token privileges, prompt-injection risk, and the privacy of agent use itself. Use PROACTIVELY when permission gating is broadly disabled (skip-permissions modes), when secrets are visible to the agent's shell, or when the agent processes untrusted code, issues or web content; when a project holds personal or confidential data while a cloud agent is active (what leaves the machine, retention, training use), or when the user asks how to run coding agents safely or privately. (Supply-chain security: rseng-security; disclosing agent contributions: rseng-ai-declaration.)

中文简介正在准备中。当前显示原文说明。

fdiblen/rseng-agent-skills242026年9月23日 更新

Covers declaring AI involvement with the AI Declaration Format (https://ai-declaration.org): creating and maintaining an aidecl.yaml that records which AI tools and agents were used, what each contributed, when and how much, plus the README disclosure footnote, JSON/JSON-LD export and CI validation. Machine-readable disclosure is the practice; this format is one implementation. Use PROACTIVELY when an AI assistant or agent creates or modifies a project's content - generate aidecl.yaml if missing, update it after AI-assisted changes. Also use when the user asks about AI transparency, provenance, disclosure or EU AI Act disclosure, wants to state that NO AI was used, or mentions aidecl. For concealment requests see rseng-honesty; for the human review duty see rseng-human-verification.

中文简介正在准备中。当前显示原文说明。

fdiblen/rseng-agent-skills242026年9月23日 更新

Covers long-term archiving of research software and data: Software Heritage save requests and SWHID persistent identifiers, Zenodo deposits with versioned DOIs and forge integration, choosing domain and institutional repositories, deciding what to archive (code, data, environments, documentation) and when, and archiving at project retirement. Use when the user wants software or data preserved beyond the life of a forge account, grant or lab, mentions Software Heritage, SWHIDs, Zenodo deposits or archiving, retires or hands over a project, prepares artifacts that must stay resolvable for a paper, or when funder policy requires long-term preservation. (Cutting the release itself is rseng-publishing-releasing; day-to-day data storage and repository choice is rseng-data-management.)

中文简介正在准备中。当前显示原文说明。

fdiblen/rseng-agent-skills242026年9月23日 更新

Covers processing research data that outgrows one machine's memory: out-of-core and chunked computation, Dask for scaling the scientific Python stack, Spark for distributed tabular pipelines, lazy evaluation, partitioning strategies, idempotent and restartable batch jobs, and knowing when NOT to distribute. Use when datasets no longer fit in memory, when the user mentions Dask, Spark, out-of-core or larger-than-memory data, when a pandas/NumPy workflow hits memory limits, or when designing batch pipelines over many files. (Cluster job submission and job arrays are rseng-hpc-computing; pipeline orchestration engines are rseng-workflows; profile first with rseng-performance-profiling.)

中文简介正在准备中。当前显示原文说明。

fdiblen/rseng-agent-skills242026年9月23日 更新

Covers continuous integration and delivery for research software: CI/CD concepts, automating builds and tests with GitHub Actions and GitLab CI/CD, and wiring an organization's GitLab CI infrastructure to a GitHub-hosted project. Use when the user asks to set up CI, write a pipeline or workflow file (.github/workflows, .gitlab-ci.yml), add automated builds/tests on push or pull request, publish a package or deploy docs when a tag or release is cut, cache dependencies to speed up CI runs, choose between GitHub Actions and GitLab CI, use self-hosted or GPU runners, mirror a repo, or report external CI status back to GitHub. For what to test and shrinking a test matrix see rseng-testing; for linter and pre-commit policy see rseng-code-quality.

中文简介正在准备中。当前显示原文说明。

fdiblen/rseng-agent-skills242026年9月23日 更新

Covers verifying that every citation is real, correct and current: checking references in manuscripts, READMEs, references files and code metadata against Crossref and OpenAlex, screening cited DOIs against the Retraction Watch database, catching fabricated or mis-attributed citations (a documented AI failure mode), and keeping bibliographies and CITATION.cff files resolvable. Use PROACTIVELY before any bibliography, reference list or citation metadata is finalized or published, whenever the agent itself has produced citations, and when the user asks to check references, mentions broken DOIs, retracted papers or citation verification, or prepares a manuscript, README or software paper with references. (Making your own software citable is rseng-citation-metadata.)

中文简介正在准备中。当前显示原文说明。

fdiblen/rseng-agent-skills242026年9月23日 更新

查看 fdiblen 的全部技能

报告此技能的问题