From f6a01705471ad897a280be272a0750caa46e4c54 Mon Sep 17 00:00:00 2001
From: Ever Winter <eternal.blizzard23@gmail.com>
Date: Sun, 19 Mar 2017 11:26:14 +0530
Subject: [PATCH] cEP-0005: Definition of aspects and tastes

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

Closes https://github.com/coala/documentation/issues/223
---
 cEP-0005.md | 54 +++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 40 insertions(+), 14 deletions(-)

diff --git a/cEP-0005.md b/cEP-0005.md
index 0b305e103..2c854b0c4 100644
--- a/cEP-0005.md
+++ b/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,6 +122,34 @@ class RedundancyBear(LocalBear):
             yield Result.from_values(aspect=aspect, ...)
 ```
 
+### Naming of aspects and tastes
+
+#### 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
 bear, we can create a new aspects class. A working implementation of the
@@ -225,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.