How far behind are comments compared to code? Are they being updated?
Inspired by "Clean Code" by Robert C. Martin, this go vet compatible tool analyses AST and git and collects details on how far comments drift from code they describe.
You need to have git with version >=2.37.
go install github.com/nikolaydubina/go-commentage@latest$ go-commentage ./...
kubernetes/pkg/util/ipset/ipset.go:283:1: "CreateSet": doc_last_updated_behind_days(1336.83)
kubernetes/pkg/util/ipset/ipset.go:296:1: "createSet": doc_last_updated_behind_days(1603.17)
kubernetes/pkg/util/ipset/ipset.go:320:1: "AddEntry": doc_last_updated_behind_days(1578.10)
kubernetes/pkg/util/ipset/ipset.go:332:1: "DelEntry": doc_last_updated_behind_days(1578.10)
kubernetes/pkg/util/ipset/ipset.go:340:1: "TestEntry": doc_last_updated_behind_days(450.07)
kubernetes/pkg/util/ipset/ipset.go:356:1: "FlushSet": doc_last_updated_behind_days(0.00)
kubernetes/pkg/util/ipset/ipset.go:364:1: "DestroySet": doc_last_updated_behind_days(73.85)
kubernetes/pkg/util/ipset/ipset.go:372:1: "DestroyAllSets": doc_last_updated_behind_days(0.00)
kubernetes/pkg/util/ipset/ipset.go:380:1: "ListSets": doc_last_updated_behind_days(0.00)
kubernetes/pkg/util/ipset/ipset.go:389:1: "ListEntries": doc_last_updated_behind_days(0.00)To narrow down output, filters can be specified. This allows interactive exploration. This also allows usage of this tool in CI, since when no diagnostic is printed then status code is 0.
$ go-commentage -min-days-behind 100 ./...
$ go-commentage -commit -min-days-behind 100 ./...
$ go-commentage -min-days-behind 10 -commit -min-days-behind 100 ./...
$ echo $?
0Measure of how far away in terms of days or commits last update of function body as compared to last update to associated doc comment.
Warning
Work in Progress
Code changes happen at various rates. Comments and code can change one line or can change 90% of lines. It is useful to differentiate between updates.
- https://git-scm.com/docs/git-blame
- https://git-scm.com/docs/git-rev-list
- https://github.com/nishanths/exhaustive
- https://github.com/kubernetes/kubernetes
This can be useful for debugging or exporting for post processing and further data visualization.
$ go-commentage -verbose -time -commit ./...
kubernetes/pkg/util/pod/pod.go:34:1: "PatchPodStatus": last_updated_at(2022-08-02T13:58:08+08:00) doc_last_updated_at(2020-02-27T06:05:33+08:00) doc_last_updated_behind_days(887.33)last_commit(04fcbd721cd3) doc_last_commit(b2528654797e) doc_last_commit_behind(8786)
kubernetes/pkg/util/pod/pod.go:74:1: "ReplaceOrAppendPodCondition": last_updated_at(2022-11-07T18:57:56+08:00) doc_last_updated_at(2022-11-07T18:57:56+08:00) doc_last_updated_behind_days(0.00)last_commit(4e732e20d05e) doc_last_commit(4e732e20d05e) doc_last_commit_behind(0)
kubernetes/pkg/util/procfs/procfs_fake.go:28:1: "GetFullContainerName": last_updated_at(2015-11-14T07:47:25+08:00) doc_last_updated_at(2017-04-04T14:16:34+08:00) doc_last_updated_behind_days(-507.27)last_commit(fb576f30c838) doc_last_commit(932ece5cfd0f) doc_last_commit_behind(-10936)
kubernetes/pkg/util/procfs/procfs_unsupported.go:34:1: "GetFullContainerName": last_updated_at(2016-08-18T23:01:03+08:00) doc_last_updated_at(2016-08-17T07:34:14+08:00) doc_last_updated_behind_days(1.64)last_commit(5eef6b8d91a2) doc_last_commit(a2824bb7a337) doc_last_commit_behind(58)
kubernetes/pkg/util/procfs/procfs_unsupported.go:40:1: "PKill": last_updated_at(2016-08-18T23:01:03+08:00) doc_last_updated_at(2016-08-18T23:01:03+08:00) doc_last_updated_behind_days(0.00)last_commit(5eef6b8d91a2) doc_last_commit(5eef6b8d91a2) doc_last_commit_behind(0)
kubernetes/pkg/util/procfs/procfs_unsupported.go:46:1: "PidOf": last_updated_at(2016-08-18T23:01:03+08:00) doc_last_updated_at(2016-08-18T23:01:03+08:00) doc_last_updated_behind_days(0.00)last_commit(5eef6b8d91a2) doc_last_commit(5eef6b8d91a2) doc_last_commit_behind(0)
kubernetes/pkg/util/removeall/removeall.go:35:1: "RemoveAllOneFilesystemCommon": last_updated_at(2021-06-04T06:38:37+08:00) doc_last_updated_at(2021-06-04T06:38:37+08:00) doc_last_updated_behind_days(0.00)last_commit(484eb0182224) doc_last_commit(484eb0182224) doc_last_commit_behind(0)
kubernetes/pkg/util/removeall/removeall.go:115:1: "RemoveAllOneFilesystem": last_updated_at(2021-06-04T06:38:37+08:00) doc_last_updated_at(2021-06-16T00:40:17+08:00) doc_last_updated_behind_days(-11.75)last_commit(484eb0182224) doc_last_commit(01bb0f86b02b) doc_last_commit_behind(-1)
kubernetes/pkg/util/removeall/removeall.go:126:1: "RemoveDirsOneFilesystem": last_updated_at(2021-06-04T06:38:37+08:00) doc_last_updated_at(2021-06-16T00:40:17+08:00) doc_last_updated_behind_days(-11.75)last_commit(484eb0182224) doc_last_commit(01bb0f86b02b) doc_last_commit_behind(-1)
kubernetes/pkg/util/rlimit/rlimit_unsupported.go:27:1: "SetNumFiles": last_updated_at(2020-02-25T13:58:28+08:00) doc_last_updated_at(2020-02-25T13:58:28+08:00) doc_last_updated_behind_days(0.00)last_commit(4936cd476bf3) doc_last_commit(4936cd476bf3) doc_last_commit_behind(0)
kubernetes/pkg/util/slice/slice.go:26:1: "CopyStrings": last_updated_at(2017-06-23T11:41:18+08:00) doc_last_updated_at(2015-01-23T06:12:37+08:00) doc_last_updated_behind_days(882.23)last_commit(f98bc7d45435) doc_last_commit(f7e3cb12a6e7) doc_last_commit_behind(19409)
kubernetes/pkg/util/slice/slice.go:37:1: "SortStrings": last_updated_at(2015-01-23T06:12:37+08:00) doc_last_updated_at(2015-01-23T06:12:37+08:00) doc_last_updated_behind_days(0.00)last_commit(f7e3cb12a6e7) doc_last_commit(f7e3cb12a6e7) doc_last_commit_behind(0)
kubernetes/pkg/util/slice/slice.go:44:1: "ContainsString": last_updated_at(2017-04-07T08:14:16+08:00) doc_last_updated_at(2017-04-07T08:14:16+08:00) doc_last_updated_behind_days(0.00)last_commit(151770c8fde9) doc_last_commit(151770c8fde9) doc_last_commit_behind(0)
kubernetes/pkg/util/slice/slice.go:58:1: "RemoveString": last_updated_at(2017-11-23T23:00:35+08:00) doc_last_updated_at(2017-11-23T23:00:35+08:00) doc_last_updated_behind_days(0.00)last_commit(e1312f2c00ed) doc_last_commit(e1312f2c00ed) doc_last_commit_behind(0)
kubernetes/pkg/util/tail/tail.go:38:1: "ReadAtMost": last_updated_at(2022-10-20T15:13:28+08:00) doc_last_updated_at(2016-12-08T04:56:06+08:00) doc_last_updated_behind_days(2142.43)last_commit(cc90e819bce9) doc_last_commit(2bb2604f0b0d) doc_last_commit_behind(29079)
kubernetes/pkg/util/tail/tail.go:68:1: "FindTailLineStartIndex": last_updated_at(2018-02-11T11:02:23+08:00) doc_last_updated_at(2016-12-08T04:56:06+08:00) doc_last_updated_behind_days(430.25)last_commit(7cfb94cbc576) doc_last_commit(2bb2604f0b0d) doc_last_commit_behind(8120)
kubernetes/pkg/util/tolerations/tolerations.go:27:1: "VerifyAgainstWhitelist": last_updated_at(2019-08-21T09:21:57+08:00) doc_last_updated_at(2017-02-28T02:34:46+08:00) doc_last_updated_behind_days(904.28)last_commit(5a50b3f4a2a2) doc_last_commit(af5379485411) doc_last_commit_behind(15293)