From 458cfd57b6727b9d9ee991fda88ec9cf3bfefdf1 Mon Sep 17 00:00:00 2001 From: Ever Winter 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 067d55970..27923f0f3 100644 --- a/cEP-0005.md +++ b/cEP-0005.md @@ -50,9 +50,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 @@ -78,12 +78,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 ``` An aspect could be writen by its fully qualified name @@ -109,15 +109,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. @@ -137,6 +135,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.
+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.
+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 @@ -238,7 +264,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.