Skip to content

Improve Documentation #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
19mdavenport merged 2 commits into from
Apr 29, 2025
Merged

Improve Documentation #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3bdb30b
improve javadocs
19mdavenport Apr 14, 2025
777f114
add README
19mdavenport Apr 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# BYU C S 240 Code Style/Quality Checker
This repository holds the source code for the "Code Quality Checker" for the BYU C S 240 class that is not part of the base checkstyle repository

The code is based on [checkstyle](https://github.com/checkstyle/checkstyle) and includes the [checkstyle built-in checks](https://checkstyle.org/checks.html). Checkstyle also allows for [writing your own custom checks](https://checkstyle.org/writingchecks.html); most of the code in this repository is either a custom check or part of a test for a custom check.

Checkstyle is based on the [Visitor Pattern](https://en.wikipedia.org/wiki/Visitor_pattern), often representing Java code in an [Abstract Syntax Tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree). Because of this, any code must compile in order to be used as input for the checker. (Note to future TA's: if C S 236 still had you building a Datalog parser, an AST is somewhat similar to the list of tokens except it's a tree instead of a list of tokens)


## Building
This repository uses Maven for dependencies and building so you can build it with `mvn package` after which a jar will be in the `target` directory as `checkstyle-<version>.jar`, like `checkstyle-1.0.8.jar`.


## Running
`java -jar path/to/jar/checkstyle-<version>.jar -c <check file name>.xml <path to files/folders to check (can be multiple)`

C S 240 Chess project running example (cs240_checks.xml is in the jar and usable from the jar, but you can substitute it if needed):

`java -jar ./checkstyle-1.0.8.jar -c cs240_checks.xml ./client/ ./server/ ./shared/`


## Code Tour
```txt
└─ src
├─ main
│ ├─ java/edu.byu.cs240.checkstyle Root folder for custom checkstyle checks
│ │ ├─ util Contains utility functionality used in multiple places
│ │ └─ <package name> Contains custom checks for a particular quality rubric category
│ │ └─ <check name>.java Contains code necessary for checking <check name>
│ └─ resources
│ ├─ checkstyle_packages.xml Informs Checkstyle where to find custom check classes
│ └─ cs240_checks.xml Informs Checkstyle which checks to run. Used as an argument when running checkstyle. Named similarly
│ to google_checks.xml and sun_checks.xml, which also appear in the jar.
└─ test
│ ├─ java/edu.byu.cs240.checkstyle Root folder for tests for the custom checkstyle checks
│ ├─ CheckTest.java Base abstract class for writing tests for custom checks
│ └─ <package name> Contains tests for custom checks for a particular quality rubric category. Most extend CheckTest
│ └─ <check name>Test.java Tests for <check name>.java inside main. Uses input files from test/resources
└─ resources
└─ edu.byu.cs240.checkstyle Root folder for code input files used to test the checks. Generally nonsense code
│ with specific problems we expect the check to find. Many contain no errors (for
│ the specified check) to make sure it doesn't flag in unexpected cases it shouldn't
└─ <package name>.testInputs.<check name> Test input files for a specific check
```
13 changes: 13 additions & 0 deletions src/main/java/edu/byu/cs240/checkstyle/readability/NestingDepth.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,12 @@
import java.util.List;
import java.util.Set;

/**
* Reports uses of nested code structures that in most styles would indent the code (if/else, loops, try/catch, switch)
* farther than a configurable number of levels
*
* @author Michael Davenport
*/
@FileStatefulCheck
public class NestingDepth extends AbstractCheck {
private static final Set<Integer> SLIST_EXCLUDED_PARENTS = Set.of(TokenTypes.METHOD_DEF, TokenTypes.LITERAL_CATCH, TokenTypes.CASE_GROUP);
Expand Down Expand Up @@ -64,6 +70,13 @@ public void leaveToken(DetailAST ast) {
}
}

/**
* Determines if the provided token should be excluded as a nesting level. Generally this is because it is
* directly tied to another token that was included. For example, "else if" would double count (the else block
* and the if statement are separate) if it wasn't excluded here.
* @param ast AST token to check
* @return true if ast should be excluded, false otherwise
*/
private boolean isExcluded(DetailAST ast) {
return isElseIf(ast) || isSListExcluded(ast) || isElseWithBracesOfIfWithoutBraces(ast) || isBlockWithBraces(ast);
}
Expand Down
1 change: 0 additions & 1 deletion src/main/java/edu/byu/cs240/checkstyle/readability/UnusedMethodReporter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
package edu.byu.cs240.checkstyle.readability;

import com.puppycrawl.tools.checkstyle.api.AbstractFileSetCheck;
import com.puppycrawl.tools.checkstyle.api.DetailAST;
import com.puppycrawl.tools.checkstyle.api.FileText;

import java.io.File;
Expand Down
1 change: 0 additions & 1 deletion src/main/java/edu/byu/cs240/checkstyle/readability/UnusedMethodWalker.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
import com.puppycrawl.tools.checkstyle.api.TokenTypes;
import edu.byu.cs240.checkstyle.util.TreeUtils;

import java.lang.invoke.MethodHandle;
import java.util.*;

/**
Expand Down