Skip to content

Commit

Permalink
cEP-0005: Definition of aspects and tastes
Browse files Browse the repository at this point in the history
Description of how aspects and tastes should be named in the future.

Closes coala/documentation#223
  • Loading branch information
Techievena committed May 12, 2017
1 parent 0138275 commit 9aa3b43
Showing 1 changed file with 37 additions and 20 deletions.
57 changes: 37 additions & 20 deletions cEP-0005.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,9 @@ paragraph:
not a program and must remain flow insensitive.
- To specify, what analysis should be run the user will not have to care about
bears. Instead, an `aspects` setting will be provided allowing the user to
specify what aspects of their code should be analyzed. Aspects could be
`spelling` or `smells` and are namespaced such that `redundancy.clones` will
be possible as well. Aspects can be defined inclusive (analyze those aspects,
specify what aspects of their code should be analyzed. aspects could be
`Spelling` or `Smell` and are namespaced such that `Redundancy.Clone` will
be possible as well. aspects can be defined inclusive (analyze those aspects,
with the `aspects` settings) or exclusive (analyze all but those aspects,
with the `ignore_aspects` setting).
- Specifying `bears` manually will still be possible as it eases use especially
Expand All @@ -77,12 +77,12 @@ max_line_length = 80
[all.python]
language = Python
files = **.py
aspects = smell, redundancy.clone # Inclusive
aspects = Smell, Redundancy.Clone # Inclusive

[all.c]
language = C
files = **.(c|h)
ignore_aspects = redundancy # Exclusive
ignore_aspects = Redundancy # Exclusive
```

### Bear API
Expand All @@ -96,15 +96,13 @@ from coalib.results.Result import Result
from coalib.bearlib.aspects import Root


class RedundancyBear(LocalBear):
# coala will run bears based on this metadata
LANGUAGES = {"C", "Python"}
# This bear is supposed to be able to fix unused imports...
FIX_ASPECTS = {Root.Redundancy.UnusedImport}
# ... and detect code clones.
DETECT_ASPECTS = {Root.Redundancy.Clone}
# To define the aspects and languages for a bear using the bear metaclass
class RedundancyBear(LocalBear, aspects={
'detect': [Root.Redundancy.Clone],
'fix': [Root.Redundancy.UnusedImport]
}, languages=['C', 'Python']):

# Aspects are passed as parameter
# aspect instances are passed as parameter
def run(self, filename, file, aspects):
# No documentation required anymore for the bears.

Expand All @@ -124,14 +122,33 @@ class RedundancyBear(LocalBear):
yield Result.from_values(aspect=aspect, ...)
```

## Aspects
An aspect should just talk about a property of something, not qualifying it. Don't name it TooLong but Length.
Then give it settings, e.g. Metadata.CommitMessage.Shortlog.Length can have a setting max_shortlog_length.
### Naming of aspects and tastes

## Settings
Do not use "allow" or "check", aspects can be turned on or off but Settings should change behaviour.
For bool: use "shortlog_colon" if it must have a colon in the shortlog. Describe the thing that should be true: "shortlog_starts_upper_case". Give as much context as needed but not more.
#### aspects

An aspect should just talk about a property of something, without qualifying
it. It should be named something like `Length` rather than `TooLong`. Then it
should be given the tastes.<br/>
For e.g. an aspect can be named as `Metadata.CommitMessage.Shortlog.Length` to
represent the length property of the shortlog (first line) of a commit message.

#### tastes

tastes are the values that are used to initialize the aspect settings. It
should not be something like `allow` or `check` which enables or disables an
aspect, rather it should be something more like a value which describes an
aspect in a specific, measurable way. It can be given as much context as
needed but not more.<br/>
For e.g. for the aspect `Metadata.CommitMessage.Shortlog.`
`FirstCharacter`, set the taste `shortlog_starts_upper_case` as true if the
shortlog must begin with a upper case letter consistently, and false if the
opposite is true.

__Note:__ aspects and tastes are orthogonal concepts and should never overlap.
Therefore extreme caution must be taken while naming aspects and tastes to
avoid any discrepancy and inconsistency in the future.

### aspectclass

The concept of aspects allows us to implement a consistency check and reduce
documentation redundancy. Instead of documenting settings and results in every
Expand Down Expand Up @@ -234,7 +251,7 @@ This allows to show more information in results. Bears can give a custom result
message; however, by default the message can be generated from the settings of
the aspects with the ``result_message`` function.

Aspects can also define a ``style_paragraph`` function that returns a small
aspects can also define a ``style_paragraph`` function that returns a small
paragraph describing how the user should write their source code according to
the given settings. This will be used to generate a full style definition from
a coala configuration.
Expand Down

0 comments on commit 9aa3b43

Please sign in to comment.