##### General

- Home
- Downloads
- Javadocs
- Mailing Lists
- Bug Tracker
- SourceForge Project
- GitHub Project

##### Running

- Ant Task Usage
- Command-Line
- Run as a Test
- Other Tools/Frameworks

##### Using

- Creating a RuleSet
- Creating a Rule
- Configuring Rules
- Starter RuleSet (All)

##### Report Types

- HTML Report
- XML Report
- Text and IDE Reports

##### Sample Reports

- Sample HTML Report
- Sample XML Report

##### Rules

- Rule Index
- Basic Rules
- Braces Rules
- Concurrency Rules
- Convention Rules
- Design Rules
- DRY Rules
- Enhanced Rules
- Exceptions Rules
- Formatting Rules
- Generic Rules
- Grails Rules
- Groovyism Rules
- Imports Rules
- JDBC Rules
- JUnit Rules
- Logging Rules
- Naming Rules
- Size/Complexity Rules
- Security Rules
- Serialization Rules
- Unnecessary Rules
- Unused Rules

##### Developing

- Developer Guide

##### Project Documentation

- Project Information
- Project Reports

## CodeNarc - Developer Guide

Contents

- The codenarc Command-line Script
- New Rule Checklist
- Before You Submit a Patch or Check-In Code

### The codenarc Command-line Script

There is a `codenarc.groovy` command-line script in the root directory of the project. It is intended to streamline common development tasks. Currently, it supports a `create-rule` task for creating new CodeNarc rules.

#### codenarc create-rule

The `create-rule` task performs the following steps:

- Prompt for the rule name
- Prompt for the existing ruleset (category) name to which the rule is added
- Create a new rule class file in the proper package (under src/main/groovy)
- Create a new rule test class file (under src/test/groovy)
- Add placeholder description messages for the new rule to "codenarc-base-messages.properties"
- Add the new rule to the chosen ruleset XML file

RUNNING

On Unix/Mac, you can run the following from the project root directory:

`./codenarc create-rule`

On Windows, you can run:

`codenarc create-rule`.

(If Windows is not configured to automatically run *.groovy files, just can run `groovy codenarc create-rule`)

AFTER YOU RUN `codenarc create-rule`

After you run `codenarc create-rule`, finish up the rule implementation, including the following:

1. Edit the generated rule class and associated test class to add the proper implementation.
2. Modify the description messages for the new rule in "codenarc-base-messages.properties". Move the message entries under the proper ruleset/category section within the file.
3. Add description to "src/main/site/apt/codenarc-rules-XX.apt" document in the site folder.
4. Run `mvn site` from the command-line. Make sure all of the tests pass and review the new rule description on the appropriate ruleset page on the project site.

### New Rule Checklist

Perform the following steps when creating a new rule. See The codenarc Command-line Script for information on the command-line script that automates a good bit of the boilerplate, as indicated below.

1. Implement the new Rule class. This is typically a subclass of `AbstractAstVisitorRule`. [1]
2. Implement the associated Rule test class. This is typically a subclass of `AbstractRuleTestCase`. [1]
3. Add the new rule class name to the appropriate RuleSet file under "src/main/resources/rulesets". [1]
4. Add the new rule description entries to "src/main/resources/codenarc-base-messages.properties". This includes both "RuleName.description" and "RuleName.description.html" property entries. [1]
5. Run `LoadAllPredefinedRuleSetsTest`.
6. Add a description of the new rule to the appropriate "src/main/site/apt/codenarc-rules-XX.apt" document.

### Before You Submit a Patch or Check-In Code

Please do the following before submitting a patch or checking in code:

- Run the full CodeNarc test suite. This includes a test called `RunCodeNarcAgainstProjectSourceCodeTest` that runs CodeNarc against its own source code (including any code that you have added or changed).

#### NOTES

- [1] These files are created (skeletons) or updated automatically if you run the `codenarc create-rule` script to create the rule. See The codenarc Command-line Script