Measurement methodology
goqu rates Go packages against one baseline, the waterlevel: the Go standard library. Every score answers the same question, how does this code measure against the code Go itself ships.
The pipeline
Packages arrive from the local module cache, from website
submissions, and from released version sweeps. Every scanned version is
resolved through the Go module proxy and analyzed twice:
go-fsck extract records every package, symbol, doc comment
and per function cyclomatic complexity; go-ddd-stats
records every file with its size. Both payloads are stored per version,
so ratings are reproducible and history accumulates. Within one
major.minor release line only the newest patch release is kept.
A release that fails to extract in place is retried from a writable
copy with a minimal go.mod; that sacrifices dependency
resolution but keeps the syntactic extraction the checks need. A
failure that survives the retry is recorded and shown on the package
page.
The waterlevel
The baseline is built from GOROOT/src (),
filtered to the standard library alone: only std/
packages, no cmd/, no testdata, no vendored code. The
current waterlevel values:
| Measure | Value |
|---|---|
| median file size | 0 B |
| median package size | 0 B |
| average cyclomatic complexity | 0 |
| 95th percentile cyclomatic complexity | 0 |
| godoc coverage of exported symbols | 0% |
| test to symbol pairing | 0% |
| Go files measured | 0 |
An exported symbol means an exported type, const, var or function, where a method only counts when its receiver type is exported too: an exported method name on an unexported type is interface plumbing, not API. All rating arithmetic is integer, in percent and permille units.
The checks
file_size_curve
The cumulative share of files under each size threshold (1 KB, 2 KB, ... 256 KB) is compared bucket by bucket against the stdlib curve, and the gaps are averaged, in permille. Small files are the desired shape: smaller files, smaller context. Matching the curve scores 100; every 3 permille of gap moves the score one point, up for a larger share of small files, down for a smaller one. The final bucket always matches by construction, which slightly dampens the average; the slope absorbs it.
median_file_size
The package's median file size against the stdlib waterlevel of
0 B, scored as 100 * waterlevel / median. A
smaller median than stdlib rises above 100, a larger one sinks below.
median_package_size
File sizes summed per package directory, median across packages,
against the stdlib waterlevel of 0 B, scored as
100 * waterlevel / median. Small, focused packages rise
above 100; sprawling ones sink below.
godoc_coverage
The share of exported symbols carrying a doc comment, scored
relative to the stdlib waterlevel of 0%:
100 * coverage / 0. Matching stdlib's discipline is
100; documenting more of the API than stdlib does rises above it.
test_ratio
Test functions (Test*; benchmarks, examples and fuzz
functions do not count) per exported symbol. The ideal is one test per
symbol; the stdlib pairing sits at 0%. A pairing of 80-100%
scores the full 100 and earns no bonus. Overtesting is penalized
proportionally: the score falls one point per percent over 100,
reaching 0 at 200%, two tests per symbol. Undertesting is penalized the
same way, falling proportionally from 100 at 80% pairing to 0 at no
tests.
complexity
The average cyclomatic complexity of all functions, scored against
the stdlib waterlevel of 0: 100 * waterlevel /
average. Simpler functions than stdlib's rise above 100.
complexity_p95
The cyclomatic complexity at the 95th percentile of all functions,
the heavy tail, against the stdlib waterlevel of 0:
100 * waterlevel / p95. The average check rewards overall
simplicity; this one penalizes hiding a few monster functions behind a
good average.
Scores, bonuses, the overall rating
Every relative check may beat the waterlevel by up to 10 points: the score is capped at 110, and the quality table shows the overhead in a separate bonus column next to the base score. test_ratio is the exception, its ideal band is worth a flat 100. The overall rating is the average of the seven checks, so a package that beats stdlib in every dimension rates up to 108/100, and the standard library itself rates 100 on every relative check by definition.
Failures never hide: a package whose newest release cannot be scanned keeps its last successful rating, with the failure reason shown on its page. Ratings recompute whenever a new version is scanned, and the history chart keeps one rated point per release line.