Extend documentation of metrics definitions (per language)

MaibornWolff / metric-gardener

BSD 3-Clause "New" or "Revised" License

5 stars 0 forks source link

Extend documentation of metrics definitions (per language) #168

Closed ce-bo closed 6 months ago

ce-bo commented 8 months ago

As a Software Auditor, I want to exactly know which language expression has been counted for a metric, so that I can explain results in detail.

I suggest to add a list of supported language feature examples per metric. Similar to what Sonar is showing. The following examples makes clear what exactly is considered for a metric of a certain language:

Java:

Copmlexity: Supporting for(var item : items), for (int i = 0; i < 10; i++), etc; Not supported: ...
Classes: Supporting classes, ....; Not Supported: not_supported_type (reason)

ResistantBear commented 8 months ago

I am a bit confused here. If I understand correctly, this is distinct from #6 because it does not refer to the concrete expression in a code file, but to the a type of expression we count for in general? So we should find out and document what expressions exactly do get parsed e.g. as "function_declaration" by tree-sitter if we count "function_declaration"? Could be a rather long list if there are so many ways to define a function, also requiring to look into the grammar to ensure that we have not missed to mention any kind of syntax to define a function.

ce-bo commented 8 months ago

Correct, this is distsinct to #6. It refers to real code examples, that are supported. I added an example on how it should look like. Let's discuss my idea. I think we as developers benefit from it as well as users. It makes it obvious which language features are already supported and which not. This leads to full transparency.

To get a feeling we maybe could start with one programming language and metric as kind of a PoC.