cEP-0005: Definition of aspects and tastes

Description of how aspects and tastes should be named in the future.

Closes coala/documentation#223

cEP-0005.md

@@ -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
@@ -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
@@ -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.
 
@@ -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
@@ -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.