| Metadata | |
|---|---|
| cEP | 10 |
| Version | 1.0 |
| Title | Convert bears to use aspects |
| Authors | Asnel Christian Ngoulla ngoullasob@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
| |--- 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 givenRoot.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 givenRoot.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 givenRoot.Formatting.Indentation.size.Root.Smell: This aspect describescode smells(smells refer to structures that violate design principles) in your codebase.Root.Smell.Complexity: describes the complexity of your code given the valuecyclomatic_complexity.Root.Smell.Complexity.cyclomatic_complexity: Variable reprensing the maximum number of embedded branches or embedded loops.Root.Smell.ClassSmell: This aslpect describescode smellsrelated 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 theCloneaspect): 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 executionRoot.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 ofcoala.Root.Spelling.aspectsYEAH: This aspect checks on the spelling ofaspect[s]andaspectsYEAH.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 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, ...)