Convert bears to use aspects

Metadata
cEP	10
Version	1.0
Title	Convert bears to use aspects
Authors	Asnel Christian Ngoulla ngoullasob@gmail.com
Status	Implementation Due
Type	Feature

Abstract

This document describes how aspects will be defined for and connected with bears and how their results will be annotated with them.

This cEP also provides a list of the aspects to be implemented with their correspponding tastes where taste are customization settings for aspects.

Introduction

An aspect is an analysis we want to run over a piece of code. As stated in cEP-0005, one of the main problems coala faces is its configuration due to the huge number of bears it offers, which are capable of analyzing several aspects of code and are sometimes highly configurable with numerous settings; whereby the user has to be aware of which bear does what and which setting has be to set to analyze the aspect he wants analyzed; resulting in a coala difficult to learn and use.

To make things easier for user the concept of aspects was created as proposed in cEP-0005. Our goal here is to list all the aspects for covering all the code anlysis features the coala bears are capable of, annotating bears' results with them.

The aspests

The bears offered by coala are usually capable of handling several aspects. aspects will be implemented in a tree-like form starting with the Root aspect. Here is the list of aspects to be implemented along with their corresponding subaspects and tastes(which are the leaves of the tree written in snake_case).

  Root
  |--- Formatting
  |    |--- UseSpaces
  |    |--- TrailingSpace
  |    |--- EmtpyLines
  |    |    |--- num_newlines_after_class_def
  |    |    |--- num_newlines_after_func_def
  |    |--- Quotation
  |    |    |--- prefered_quotation
  |    |--- Length
  |    |    |--- LineLength
  |    |    |    |--- max_line_length
  |    |    |--- Ignore
  |    |    |    |--- ignore_links
  |    |    |    |--- ignore_line
  |    |    |--- FileLength
  |    |    |    |--- max_file_length
  |    |    Indentation
  |    |    |--- size
  |    |--- ParenthesesFormatting
  |    |--- BracesFormatting
  |    |--- SpaceAroundOperators
  |--- Smell
  |    |--- Complexity
  |    |    |--- cyclomatic_complexity
  |    |--- ClassSmell
  |    |    |--- ClassLength
  |    |    |    |--- max_class_length
  |    |    |    |--- min_class_length
  |    |    |--- FeatureEnvy
  |    |    |--- DataClump
  |    |--- MethodSmell
  |    |    |--- max_method_length
  |    |    |--- max_parameter
  |    |--- Naming
  |    |    |--- variable_naming_convention
  |    |    |--- function_naming_convention
  |    |    |--- class_naming_convention
  |    |    |--- max_indentifier_name_length
  |    |    |--- min_indentifier_name_length
  |--- Security
  |    |--- buffer_overflow
  |    |--- unallocated_memory
  |--- Redundancy
  |    |--- Clone
  |    |    |--- min_clone_tokens
  |    |    |--- ignore_using
  |    |--- UnusedImport
  |    |--- UnreachableCode
  |    |--- UnusedFunction
  |    |--- UnreachableStatement
  |    |--- UnusedParameter
  |    |--- UnusedLocalVariable
  |    |--- UnusedGlobalVariablee
  |--- Spelling
  |    |--- aspectsYEAH
  |    |--- coalaCorrect
  |--- UndefinedElement
  |    |--- UndefinedVariable
  |    |--- UndefinedParameter
  |    |--- UndefinedFunction
  |--- Documentation
  |--- Grammar
  |    |--- Language
  |--- Metadata
       |--- CommitMessage
            | --- Shortlog
            | --- |--- Emptiness
            | --- |--- ColonExistence
            | --- |--- TrailingPeriod
            | --- |--- Tense
            | --- |--- Length
            | --- |--- |--- max_shortlog_length
            | --- |--- FirstCharacter
            | --- |--- |--- shortlog_starts_upper_case
            | --- Body
                  |--- Existence
                  |--- Length
                       |--- max_body_length

Root.Formatting: This aspect checks on the format (the structure) of your codebase.
Root.Formatting.UseSpaces: This aspect enforces the use of spaces over tabs.
Root.Formatting.TrailingSpace: This aspect detects trailing spaces in the code.
Root.Formatting.EmptyLines: This aspect checks on empty lines.
Root.Formatting.EmptyLines.num_newlines_after_class_def: This taste represents the number of newlines that should be added after a class definition.
Root.Formatting.EmptyLines.num_newlines_after_func_def: This taste represents the number of newlines that should be added after a function definition.
Root.Formatting.Quotation: This aspect checks on the quotations being used in your files given Root.Formatting.Quotation.prefered_quotation.
Root.Formatting.Quotation.prefered_quotation: This taste represents the user's preferred quotation.
Root.Formatting.LineLength: This aspect checks on lines' length in your codebase.
Root.Formatting.LineLength.max_line_length: This taste represents that maximum length for line.
Root.Formatting.LineLength.Ignore: This aspect represents all the elements to be ignored.
Root.Formatting.LineLength.Ignore.ignore_links: this taste is to determine whether links should be ignored while checking on lines' length.
Root.Formatting.LineLength.Ignore.ignore_line: this taste is to which line should be ignored while checking on lines' length.
Root.Formatting.FileLength: This aspect checks on files' length given Root.Formatting.FileLength.max_file_length.
Root.Formatting.FileLength.max_file_length: this taste represents the maximum length for a file.
Root.Formatting.Indentation: This taste checks on the number of space used for indentation given Root.Formatting.Indentation.size.
Root.Smell: This aspect describes code smells (smells refer to structures that violate design principles) in your codebase.
Root.Smell.Complexity: describes the complexity of your code given the value cyclomatic_complexity.
Root.Smell.Complexity.cyclomatic_complexity: Variable reprensing the maximum number of embedded branches or embedded loops.
Root.Smell.ClassSmell: This aslpect describes code smells related to classes' definition in your codebase.
Root.Smell.ClassSmell.ClassLength: This aspect deals with the length of classes' definition.
Root.Smell.ClassSmell.ClassLength.max_class_length: This taste represents the maximum length for a class's definition.
Root.Smell.ClassSmell.ClassLength.min_class_length: This taste represents the minimum length for a class's definition.
Root.Smell.ClassSmell.FeatureEnvy: This aspect describes classes that use other classes' methods excessively.
Root.Smell.ClassSmell.DataClump: This aspect describes variables are passed around together in various parts of the program, suggesting that they should pass as a single object.
Root.Smell.MethodSmell: This aspect describes code smells related to functions' (and or methods') definition.
Root.Smell.MethodSmell.max_method_length: variable representing the maximum length for a method or a function definition.
Root.Smell.MethodSmell.max_parameter: This taste represents maximum number of paramters for a function.
Root.Smell.Naming: This aspect deals with identifiers' names(their length, the naming convention in use ...)
Root.Smell.Naming.variable_naming_convention: This taste represents the naming convention used for variables' and functions' parameters' identifiers.
Root.Smell.Naming.function_naming_convention: This taste represents the naming convention used for functions' or methods'.
Root.Smell.Naming.class_naming_convention: This taste represents the naming convention being used for classes.
Root.Smell.Naming.max_identifier_length: This taste represents the max length for an identifier.
Root.Smell.Naming.min_identifier_length: This taste represents the min length for an identifier.
Root.Redundancy: This aspect describes redundancy in your source code.
Root.Redundancy.Clone: This aspect detects code clones or more specifically very similar blocks of code in your codebase.
Root.Redundancy.Clone.min_clone_tokens(a taste of the Clone aspect): Thsi taste represents the minimun number of token that have to be equal to be considered as a clone.
Root.Redundancy.UnusedImport: This taste describes useless import/include that is not needed.
Root.Redundancy.UnreachableCode: This taste describes source code that can never be executed during the program execution.
Root.Redundancy.UnusedFunction: This taste describes functions that are never called during code execution
Root.Redundancy.UnreachableStatement: This taste describes statement that are never executed during code execution.
Root.Redundancy.UnusedParameter: This taste describes functions' parameters which are never used.
Root.Redundancy.UnusedLocalVariable: This taste describes variables which are defined locally but never used.
Root.Redundancy.UnusedGlobalVariable: this taste describes variables which have a global scope but are never used.
Root.Spelling: This aspect checks on the spelling of specific words.
Root.Spelling.coalaCorrect: This aspect checks on the spelling of coala.
Root.Spelling.aspectsYEAH: This aspect checks on the spelling of aspect[s] and aspectsYEAH.
Root.UndefinedElement: This aspect checks on undefined element in your codebase.
Root.UndefinedElement.UndefinedVariable: This aspect detects undefined variables in your code.
Root.UndefinedElement.UndefinedParameter: This aspect detects undefined parameters in functions' definitions.
Root.UndefinedElement.UndefinedFunction: This aspect detects undefined functions in your codebase.
Root.Metadata: This describes any aspect that is related to metadata that is not inside your source code.
Root.Metadata.CommitMessage.
Root.Metadata.CommitMessage.Emptiness: This aspect is to detect and prevent from using empty commit message.
Root.Metadata.CommitMessage.Shortlog: This aspect checks on the first line of your commit message.
Root.Metadata.CommitMessage.Shortlog.ColonExistence: This aspect checks your commit shortlog to see whether or not there is a colon (given that the usage of colon is compulsory in your project).
Root.Metadata.CommitMessage.Shortlog.TrailingPeriod: This aspect checks for trailing period.
Root.Metadata.CommitMessage.Shortlog.Tense: This aspect checks on the tense used in commit message shortlog.
Root.Metadata.CommitMessage.Shortlog.Length: This aspect checks on the length of your commit message shortlog given the value of Root.Metadata.CommitMessage.Shortlog.Length.max_shortlog_length.
Root.Metadata.CommitMessage.Shortlog.FirstCharacter: This aspect detects inconsistent casing for the first character of your commit message shortlog( and the the first character following the colon if there is one) given the value of Root.Metadata.CommitMessage.Shortlog.FirstCharacter.shortlog_starts_upper_case [taste representing the case to use for the first character of your commit message shortlog and the first character following the colon].
Root.Metadata.CommitMessage.Body: Parent aspect for all of the aspects related to your commit message body.
Root.Metadata.CommitMessage.Body.Existence: Checks on the existence of your commit message body (it enforces its usage).
Root.Metadata.CommitMessage.Body.Length: Checks on the length of your commit message body given the value of Root.Metadata.CommitMessage.Body.Length.max_body_length.

Implementation

As stated previously the aspects will be implemented in a tree like form, with the Root aspect at the root of the tree. Some classes, metaclasses and some few methods were define so far to make that possible including:

the aspectbase class
the Documentation class for documenting aspects
the aspectclass metaclass
the TasteMeta class
the Taste class

aspects will simply be defined this way:

from coalib.bearlib.aspects import Root, Taste


@Root.subaspect
class SomeAspect:

    # This will serve as documentation for the aspect
    class docs:
        example = 'an example of this aspect of code'
        example_language = 'the programming language of the example'
        importance_reason = 'the reason why this is important'
        fix_suggestions = ''

    # Here we define the different tastes for this aspect
    # aspects are not compelled to have tastes
    some_taste = Taste[Taste_type](
        'Documentation about this taste',
        list('Possible value for this taste',),
        default='Default value for this taste')

The documentation of each of the implemented aspects will be added to the coala/aspect-docs repository.

Concerning bears' results annotation, so far, the .aspect attr was added to the Result class (where a Result object is what is yielded by a bear when through executing). So annotating a bear's result with aspects simply consists of setting this variable to the appropriate aspect of code. Here is how bears' will be defined in as presented in cEP-0005.

from coalib.bears.LocalBear import LocalBear
from coalib.results.Result import Result
from coalib.bearlib.aspects import Root


class RedundancyBear(LocalBear, aspects={
        # This represents all the aspects this bear can detect.
        'detect': [Root.Redundancy.Clone],
        # This represents all the aspects this bear can fix.
        'fix': [Root.Redundancy.UnusedImport]},
        languages=['C', 'Python']):

    def run(self, filename, file, aspects):
        # No documentation required anymore for the bears.

        if unused_imports(file):
            # A bear may yield results for any aspect even if it's not selected.
            # coala will filter out only selected aspects.
            yield Result.from_values(aspect=Root.Redundancy.UnusedImport, ...)

        # Bears can save performance by only performing needed checks
        aspect = aspects.get(Root.Redundancy.Clone, False)
        if aspect:
            # Bears can access tastes right from the aspect instance
            min_clone_tokens = aspect.min_clone_tokens

            # The aspect is tied to the result. coala now knows everything from
            # the aspect documentation!
            yield Result.from_values(aspect=aspect, ...)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cEP-0010.md

cEP-0010.md

Convert bears to use aspects

Abstract

Introduction

The aspests

Implementation

Files

cEP-0010.md

Latest commit

History

cEP-0010.md

File metadata and controls

Convert bears to use aspects

Abstract

Introduction

The aspests

Implementation