Rework the metrics used by the FileTree #161
Conversation
Pennycook
added
documentation
Pennycook
force-pushed
the
metric-rework
branch
from
43fe59c to
ca90a0d
Compare
Presenting the amount of code used by all platforms as "coverage" is more aligned with how we describe CBI's functionality elsewhere. Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
Small refactoring to enable later re-use. Signed-off-by: John Pennycook <[email protected]>
This has several advantages: - It wastes less whitespace than printing two SLOC counts. - The reader doesn't have to perform division to calculate coverage. - We can easily color-code coverage to highlight good/bad values. Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
Computing coverage relative to a set of platforms enables the function to be used in more contexts. Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
- Mention "platform coverage" in README and home page. - Add a description of "platform coverage" to the specialization page. Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
Pennycook
force-pushed
the
metric-rework
branch
from
41db7a9 to
89144ea
Compare
|
The merge was too complicated for GitHub (because a file that was modified elsewhere was deleted here) so I had to rebase. @laserkelvin, this is safe to review now. |
codebasin/report.py
Outdated
| platforms: set[str] | None = None, | ||
| ) -> float: | ||
| """ | ||
| Compute the average percentage of lines in `setmap` required by each |
There was a problem hiding this comment.
I would suggest a minor rephrasing - not sure if it's just my brain but when I mention reductions in text I try and move it away from the original quantity and be explicit about what the reduction is over.
In this case, "...percentage of lines in setmap required by each platform in the supplied platforms set, **averaged over the set of platforms." Similar to how you've written it for the output description.
There was a problem hiding this comment.
This broke my brain a little bit. 😆
I think which form I'd prefer to use depends on context. I'd definitely say something like "temperature, averaged over volume", but in this case I think it's important to emphasize at the beginning of the sentence that what we are returning is an average .
I've tried to split the difference, and made two changes. In e45edc6, I broke down the behavior of the function to explain what we're computing:
Computes the coverage for each platform in the supplied `platforms` set
(by calling :py:func:`coverage` for each platform), then returns the
average (mean) of these values.
...and then in 29fc127 I added the missing Returns sections, with shorter sentences that are hopefully easier to parse, e.g.:
The average amount of code used by each platform, as a percentage.
Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
2 participants
Related issues
Proposed changes
FileTreeoutput by focusing in "coverage" metrics and removing redundant information.The new report output is much more readable than the old one:
I've opened this as a draft to ensure that we don't accidentally merge it before #158, but I think the functionality is ready for review.