| Metadata | |
|---|---|
| cEP | 10 |
| Version | 1.0 |
| Title | Convert bears to use aspects |
| Authors | Asnel Christian Ngoulla mailto:ngoullasob@gmail.com |
| Pareksha Manchanda mailto:pareksha.manchanda@gmail.com | |
| Status | Implementation Due |
| Type | Feature |
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.
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 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
| |--- Quotation
| | |--- preferred_quotation
| |--- Length
| | |--- LineLength
| | | |--- max_line_length
| | |--- FileLength
| | | |--- max_file_length
| | | |--- min_file_length
| |--- Spacing
| | |--- Indentation
| | | |--- indent_type
| | | |--- indent_size
| | |--- TrailingSpace
| | | |--- allow_trailing_spaces
| | |--- BlankLine
| | | |--- BlankLineAfterDeclaration
| | | | |--- blank_lines_after_declarations
| | | | |--- BlankLineAfterProcedure
| | | | |--- BlankLineAfterClass
| | | | |--- NewlineAtEOF
| | |--- SpacesAroundOperator
| | | |--- spaces_around_operators
| | | |--- spaces_before_colon
| | | |--- spaces_after_colon
|--- Smell
| |--- Complexity
| | |--- CyclomaticComplexity
| | | |--- cyclomatic_complexity
| | |--- MaintainabilityIndex
| | | |--- maintainability_index
| |--- ClassSmell
| | |--- ClassSize
| | | |--- ClassLength
| | | | |--- max_class_length
| | | |--- ClassConstants
| | | | |--- max_constants
| | | |--- ClassInstanceVariables
| | | | |--- max_instance_variables
| | | |--- ClassMethods
| | | | |--- max_methods
| |--- FeatureEnvy
| |--- DataClump
| |--- MethodSmell
| | |--- MethodLength
| | | |--- max_method_length
| | | |--- method_length_count_comment
| | |--- ParameterListLength
| | | |--- max_parameters
| |--- Naming
| | |--- variable_naming_convention
| | |--- function_naming_convention
| | |--- class_naming_convention
| | |--- max_identifier_length
|--- Security
|--- Redundancy
| |--- Clone
| | |--- min_clone_tokens
| | |--- ignore_using
| |--- UnusedImport
| | |--- remove_non_standard_import
| |--- UnreachableCode
| | |--- UnusedFunction
| | |--- UnreachableStatement
| |--- UnusedVariable
| | |--- UnusedParameter
| | |--- UnusedLocalVariable
| | |--- UnusedGlobalVariable
|--- Spelling
| |--- DictionarySpelling
| |--- OrgSpecificWordSpelling
| | |--- specific_word
|--- Metadata
|--- CommitMessage
|--- Shortlog
| |--- ColonExistence
| | |--- shortlog_colon
| |--- TrailingPeriod
| | |--- shortlog_period
| |--- Tense
| | |--- shortlog_tense
| |--- Length
| | |--- max_shortlog_length
| |--- FirstCharacter
| | |--- shortlog_starts_upper_case
|--- Emptiness
|--- Body
|--- Existence
|--- Length
|--- max_body_length
Root.Formatting: This aspect checks on the format (the structure) of your codebase.Root.Formatting.Quotation: This aspect checks on the quotations being used in your files givenRoot.Formatting.Quotation.preferred_quotation.Root.Formatting.Quotation.preferred_quotation: This taste represents the user's preferred quotation.Root.Formatting.Length: This aspect holds sub-aspects for file and line length.Root.Formatting.LineLength: This aspect checks on lines' length in your codebase.Root.Formatting.LineLength.max_line_length: This taste represents the maximum length for line.Root.Formatting.FileLength: This aspect checks on files' length givenRoot.Formatting.FileLength.max_file_lengthorRoot.Formatting.FileLength.min_file_length.Root.Formatting.FileLength.max_file_length: This taste represents the maximum length for a file.Root.Formatting.FileLength.min_file_length: This taste represents the minimum number of lines per file.Root.Formatting.Spacing: This aspect is for removing whitespace between non-whitespace characters.Root.Formatting.Spacing.Indentation: This aspect checks for type and size of indent given the respective aspects.Root.Formatting.Spacing.Indentation.indent_type: This taste represents type of indentation used.Root.Formatting.Spacing.Indentation.indent_size: This taste represents size of indentation used.Root.Formatting.Spacing.TrailingSpace: This aspect checks for unnecessary whitespace at end of line givenallow_trailing_spaces.Root.Formatting.Spacing.BlankLine: This aspect is for lines with no characters.Root.Formatting.Spacing.BlankLine.BlankLineAfterDeclaration: This aspect represents the number of blank lines after declarations.Root.Formatting.Spacing.BlankLine.BlankLineAfterProcedure: This aspect represents the number of blank lines after procedure and function.Root.Formatting.Spacing.BlankLine.BlankLineAfterClass: This aspect represents the number of blank lines after class.Root.Formatting.Spacing.BlankLine.NewlineAtEOF: This aspect is for a blank line at the end of line givenRoot.Formatting.Spacing.BlankLine.NewlineAtEOF.newline_at_EOF.Root.Formatting.Spacing.BlankLine.SpacesAroundOperator: This aspect is for spacing around operators.Root.Formatting.Spacing.BlankLine.SpacesAroundOperator.spaces_around_operators: This taste represents number of space to be used around operators.Root.Formatting.Spacing.BlankLine.SpacesAroundOperator.spaces_before_colon: This taste represents number of blank spaces before colons..Root.Formatting.Spacing.BlankLine.SpacesAroundOperator.spaces_after_colon: This taste represents number of blank spaces after colons.Root.Smell: This aspect describescode smells(smells refer to structures that violate design principles) in your codebase.Root.Smell.Complexity: This aspect describes the complexity of your code according to various metrics.Root.Smell.Complexity.CyclomaticComplexity: This aspect represents the maximum number of embedded branches or embedded loops.Root.Smell.Complexity.CyclomaticComplexity.cyclomatic_complexity: Taste representing the maximum number of embedded branches or embedded loops allowed.Root.Smell.Complexity.MaintainabilityIndex: This aspect represents the maintainability of code.Root.Smell.Complexity.MaintainabilityIndex.maintainability_index: This taste sets the maintainability index of code.Root.Smell.ClassSmell: This aspect describescode smellsrelated to classes' definition in your codebase.Root.Smell.ClassSmell.ClassSize: This aspect deals with the size of a class.Root.Smell.ClassSmell.ClassSize.ClassLength: This aspect deals with the length of class definition.Root.Smell.ClassSmell.ClassSize.ClassLength.max_class_length: This taste represents the maximum length for a class's definition.Root.Smell.ClassSmell.ClassSize.ClassConstants: This aspect represents number of constants in a class.Root.Smell.ClassSmell.ClassSize.ClassConstants.max_constants: This taste represents maximum number of constants allowed in a class.Root.Smell.ClassSmell.ClassSize.ClassInstanceVariables: This aspect represents number of instance variables in a class.Root.Smell.ClassSmell.ClassSize.ClassInstanceVariables.max_instance_variables: This taste represents the maximum number of instance variables in a class.Root.Smell.ClassSmell.ClassSize.ClassMethods: This aspect represents number of class methods in a class.Root.Smell.ClassSmell.ClassSize.ClassMethods.max_methods: This taste represents the maximum number of class methods in a class.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.MethodLength: This aspect represents number of lines of code for a function or method definition.Root.Smell.MethodSmell.MethodLength.max_method_length: This taste represents the maximum length for a method or a function definition.Root.Smell.MethodSmell.MethodLength.method_length_count_comment: This taste represents whether to consider comments while calculating methods' length.Root.Smell.MethodSmell.ParameterListLength: This aspect represents number of parameters for a function or method definition.Root.Smell.MethodSmell.ParameterListLength.max_parameters: This taste represents maximum number of paramters for a function or a method.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.Security: This aspects checks for code with flaws or security weaknesses.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: This taste represents the minimum number of tokesn that have to be equal to be considered as a clone.Root.Redundancy.Clone.ignore_using: This taste represents ignore using directives in C#.Root.Redundancy.UnusedImport: This taste describes useless import/include that is not needed.Root.Redundancy.UnreachableCode: This taste describes source code that is never be executed during the program execution.Root.Redundancy.UnreachableCode.UnusedFunction: This taste describes functions that are never called during code executionRoot.Redundancy.UnreachableCode.UnreachableStatement: This taste describes statement that are never executed during code execution.Root.Redundancy.UnusedVariable: This taste describes unused variables are declared but never used.Root.Redundancy.UnusedVariable.UnusedParameter: This taste describes functions' parameters which are never used.Root.Redundancy.UnusedVariable.UnusedLocalVariable: This taste describes variables which are defined locally but never used.Root.Redundancy.UnusedVariable.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.DictionarySpelling: This aspect checks for valid language's words spelling.Root.Spelling.OrgSpecificWordSpelling: This aspect checks for specified words' spelling in organisations like coala.Root.Spelling.OrgSpecificWordSpelling.specific_word: This taste represents the regex of the specific word to check.Root.Metadata: This describes any aspect that is related to metadata that is not inside your source code.Root.Metadata.CommitMessage: This aspect is for commit messages associated with your source code.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) givenRoot.Metadata.CommitMessage.Shortlog.ColonExistence.shortlog_colon.Root.Metadata.CommitMessage.Shortlog.TrailingPeriod: This aspect checks for trailing period in commit message shortlog givenRoot.Metadata.CommitMessage.Shortlog.TrailingPeriod.shortlog_period.Root.Metadata.CommitMessage.Shortlog.Tense: This aspect checks on the tense used in commit message shortlog.Root.Metadata.CommitMessage.Shortlog.Tense.shortlog_tense: This taste represents the tense to be used for the shortlog.Root.Metadata.CommitMessage.Shortlog.Length: This aspect checks on the length of your commit message shortlog given the value ofRoot.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 ofRoot.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 ofRoot.Metadata.CommitMessage.Body.Length.max_body_length.
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, ...)