This tool aims to enforce coding conventions determined by TaleWorlds Entertainment. In the main part of the code, the Roslyn API is used to analyze and assign a fixer to the diagnostics. The general structure of the code is based on a MVC-like pattern. As a base of the extension, we have used XML files and analyzers by using the XML files. On top of them, we have a controller and a command to control this extension.
- The maximum allowed depth can be controlled from the controller window.
- The code fixes and reanalyze has conflicted in the final test. Need to be fixed.
The analyzers have been designed to be as atomic as they should be. Their explanations can be found in the following.
This analyzer is responsible for checking whether an abstract class has only abstract methods or empty virtual methods.
This analyzer is responsible for checking whether the class has exceeded the maximum allowed depth of inheritance. The permitted maximum depth can be adjusted from the code.
This analyzer is responsible for checking whether the overridden method is sealed. It should be sealed to prevent overriding them again.
In these types of analyzers, the purpose is to report diagnostics if any violation is present. Alongside that, we have tried to suggest some names for these analyzers.
The naming-related analyzers use the same conventions as PascalCase of camelCase. These conventions act slightly differently from each other. Therefore, we have created a behavior inheritance tree to create more manageable and readable code. Each analyzer acts differently, but the main goal is checking whether the declared name is suitable to its related convention. The table to demonstrate the ideal naming is the following:
The classes should be named according to the _uscoreCase if it is internal or private. However, it should be named according to the PascalCase if it is public.
The fields should be named according to the _uscorCase if it is private.
The interfaces should be named according to the IPascalCase.
The variables declared in the local scope should be named according to camelCase.
The methods should be named according to the _uscoreCase if it is internal or private. However, it should be named according to the PascalCase if it is public or protected.
The parameters should be named according to the camelCase.
The properties should be named according to the _uscoreCase if it is internal or private. However, it should be named according to the PascalCase if it is public or protected.
The template parameters should be named according to the TPascalCase.
The classes should not have protected accessibility.
The fields should not have public, protected, or internal accessibility.
This analyzer checks whether the structs with only one field are immutable or not.
This analyzer checks whether any declared property or method has mixed access modifiers or not.
This analyzer creates a diagnostic if any local variable has an explicit type. The var keyword should be rather than that.
This analyzer reports diagnostics if any method call has more parameters than the allowed argument threshold, and these arguments are not specifically named.
In the project, there are unit tests for analyzers and behaviors. The external controllers haven't been tested as unit tests, yet.
The analyzers should have TaleworldsAnalyzer Attribute. Thanks to this attribute, the new analyzers can be added without any changes. The analyzers that have this attribute are found by the FindAnalyzers class. This class uses reflection to find all Taleworlds Analyzers.
The analyzing pipeline has several steps, you can find specific information regarding to the steps as the document goes. The first thing the program does is determine whether the analysis is needed or not. The PreAnalyzerConditions class is used to create such control. The inheritance and other checkers categories directly jump to the analyzing logic. However, the name checkers need to check the white list that is added by the user. These white-listed words will be ignored in the analyzing logic.
The PreAnalyzerConditions class is used to create such checks. The analysis is not needed if the project is black-listed, the context has related disabling comments on the code, or the severity of related diagnostic is adjusted as none.
The user can add the project to the local black-list to ignore it. The user needs to press the right mouse click on the project then an option appears as Add to the BlackList. Users can press this.
The user can add some words to the white list. Whitelist control can be done via the controller window. Also, name checkers have code fixes about adding to the white list. White-listed words will be ignored in the name checkers. There are 2 white lists which are local and shared. Local is stored in appdata of the computer, while the shared one is stored in the project path.
The user can write disabling and enabling comments. "//TWCodeAnalysis disable {Insert Diagnostic ID Here}" disables the written diagnostic until it is enabled again by writing "//TWCodeAnalysis enable {Insert Diagnostic ID Here}". Similarly, all diagnostics can be disabled by writing "//TWCodeAnalysis disable all", and can be enabled by writing "//TWCodeAnalysis disable all". In addition to that, the user can disable the diagnostic for only one line by using "//TWCodeAnalysis disable next line all" and "//TWCodeAnalysis disable next line {Insert Diagnostic ID Here}"
The user can set custom severity for each diagnostic by using the controller window. These settings can be found in the solution path.
There are two code fixer providers in the project.
In this fix provider, the user can add disabling comments without writing them directly. However, The enable command should be written directly.
In this fix provider, the user can add a forbidden part of the declaration to the local or shared white list.
There are two editor commands, and one of them is already stated in the blacklist feature. The second one is for opening the controller window. The controller can be found in the View -> Other Windows -> Taleworlds Code Analysis.
The controller has several functionalities to create ease of use for the extension. There is a refresh button that refreshes the analyzers and settings. Next, there are presets for all analyzers, but if the user wants, he/she can set different severity for each analyzer. After adjusting the severities, the user should press the save button to apply them. Furthermore, there is a white-list panel to control white-listed items. White-listed words can be controlled from here.
The extension has several different components. The first two components are the controller window and blacklist command. These two components are connected to the main analyzer .vsix file. Therefore, you need to build them all to create an up-to-date .vsix file.
After building the project, there will be one extension called TaleworldsCodeAnalysis.vsix . This is the only .vsix file to install directly to Visual Studio.
Berkay Karakaya - Arınç Demir with supervises of Oğuzhan Şirin