The Power of Custom Lint Checks

Presented at the droidcon Berlin 2015:
http://droidcon.de/session/power-custom-lint-checks

You can find the recorded talk here:
https://www.youtube.com/watch?v=td7RzzBhBfk

Nearly every Android developer knows about the Lint toolset which comes bundled with the Android SDK - however not many use it to its full power, if at all. Lint can help prevent wrong usage of the SDK APIs, and enforce not only code style, but also internal architecture conventions. For example, you have a fancy BaseFragment which should be extended by all your Fragments, or you have a custom logger which should be used instead of android.util.Log. Both of these are perfect use cases for custom Lint checks.

This talk will show you how to use the APIs to create custom Lint checks, and how to include them in your Gradle-based project.

Transcript

1. The Power of Custom Lint Checks droidcon Berlin | 05.06.2015 | Marc Prengemann
2. About me Marc Prengemann Working student Mail: marc@wire.com Wire: marcprengemann@gmail.com Github: winterDroid Google+: Marc Prengemann
3. Lint? What?
4. What is Lint? http://developer.android.com/tools/help/lint.html
5. When should I use Lint? • To ensure code quality • Focus in reviews on real code • Prevent people from misusing internal libraries … but what are the challenges? • @Beta • Getting familiar with the Lint API • Integrating within your Gradle Build • Debugging / Testing
6. Getting started with own Checks
7. Test ideas • Fragments and Activities should extend your BaseClass • Use ViewUtils instead of finding and casting a View • Don’t check floats for equality - use Float.equals instead • Find leaking resources • Enforce Naming conventions • Find hardcoded values in XMLs
8. A real example • Timber • logger by Jake Wharton • https://github.com/JakeWharton/ timber • want to create a detector that finds misuse of android.util.Log instead of Timber
9. Detector • responsible for scanning through code and to find issues and report them public class WrongTimberUsageDetector extends Detector implements Detector.JavaScanner {
 
 public static final Issue ISSUE = ...;
 
 @Override
 public List<String> getApplicableMethodNames() {
 return Arrays.asList("v", "d", "i", "w", "e", "wtf");
 }
 
 @Override
 public void visitMethod(@NonNull JavaContext context, 
 AstVisitor visitor, 
 @NonNull MethodInvocation node) {
 if (!(node.astOperand() instanceof VariableReference)) {
 return;
 }
 VariableReference ref = (VariableReference) node.astOperand();
 if ("Log".equals(ref.astIdentifier().astValue())) {
 context.report(ISSUE,
 node,
 context.getLocation(node),
 "Using 'Log' instead of 'Timber'");
 }
 }
 }
10. Detector • responsible for scanning through code and to find issues and report them • most detectors implement one or more scanner interfaces that depend on the specified scope • Detector.XmlScanner • Detector.JavaScanner • Detector.ClassScanner public class WrongTimberUsageDetector extends Detector implements Detector.JavaScanner {
 
 public static final Issue ISSUE = ...;
 
 @Override
 public List<String> getApplicableMethodNames() {
 return Arrays.asList("v", "d", "i", "w", "e", "wtf");
 }
 
 @Override
 public void visitMethod(@NonNull JavaContext context, 
 AstVisitor visitor, 
 @NonNull MethodInvocation node) {
 if (!(node.astOperand() instanceof VariableReference)) {
 return;
 }
 VariableReference ref = (VariableReference) node.astOperand();
 if ("Log".equals(ref.astIdentifier().astValue())) {
 context.report(ISSUE,
 node,
 context.getLocation(node),
 "Using 'Log' instead of 'Timber'");
 }
 }
 }
11. Detector • responsible for scanning through code and finding issue instances and reporting them • most detectors implement one or more scanner interfaces • can detect multiple different issues • allows you to have different severities for different types of issues public class WrongTimberUsageDetector extends Detector implements Detector.JavaScanner {
 
 public static final Issue ISSUE = ...;
 
 @Override
 public List<String> getApplicableMethodNames() {
 return Arrays.asList("v", "d", "i", "w", "e", "wtf");
 }
 
 @Override
 public void visitMethod(@NonNull JavaContext context, 
 AstVisitor visitor, 
 @NonNull MethodInvocation node) {
 if (!(node.astOperand() instanceof VariableReference)) {
 return;
 }
 VariableReference ref = (VariableReference) node.astOperand();
 if ("Log".equals(ref.astIdentifier().astValue())) {
 context.report(ISSUE,
 node,
 context.getLocation(node),
 "Using 'Log' instead of 'Timber'");
 }
 }
 }
12. Detector • responsible for scanning through code and finding issue instances and reporting them • most detectors implement one or more scanner interfaces • can detect multiple different issues • define the calls that should be analyzed • overwritten method depends on implemented scanner interface • depends on the goal of the detector public class WrongTimberUsageDetector extends Detector implements Detector.JavaScanner {
 
 public static final Issue ISSUE = ...;
 
 @Override
 public List<String> getApplicableMethodNames() {
 return Arrays.asList("v", "d", "i", "w", "e", "wtf");
 }
 
 @Override
 public void visitMethod(@NonNull JavaContext context, 
 AstVisitor visitor, 
 @NonNull MethodInvocation node) {
 if (!(node.astOperand() instanceof VariableReference)) {
 return;
 }
 VariableReference ref = (VariableReference) node.astOperand();
 if ("Log".equals(ref.astIdentifier().astValue())) {
 context.report(ISSUE,
 node,
 context.getLocation(node),
 "Using 'Log' instead of 'Timber'");
 }
 }
 }
13. Detector • responsible for scanning through code and finding issue instances and reporting them • most detectors implement one or more scanner interfaces • can detect multiple different issues • define the calls that should be analyzed • analyze the found calls • overwritten method depends on implemented scanner interface • depends on the goal of the detector public class WrongTimberUsageDetector extends Detector implements Detector.JavaScanner {
 
 public static final Issue ISSUE = ...;
 
 @Override
 public List<String> getApplicableMethodNames() {
 return Arrays.asList("v", "d", "i", "w", "e", "wtf");
 }
 
 @Override
 public void visitMethod(@NonNull JavaContext context, 
 AstVisitor visitor, 
 @NonNull MethodInvocation node) {
 if (!(node.astOperand() instanceof VariableReference)) {
 return;
 }
 VariableReference ref = (VariableReference) node.astOperand();
 if ("Log".equals(ref.astIdentifier().astValue())) {
 context.report(ISSUE,
 node,
 context.getLocation(node),
 "Using 'Log' instead of 'Timber'");
 }
 }
 }
14. Detector • responsible for scanning through code and finding issue instances and reporting them • most detectors implement one or more scanner interfaces • can detect multiple different issues • define the calls that should be analyzed • analyze the found calls • report the found issue • specify the location • report() will handle to suppress warnings • add a message for the warning public class WrongTimberUsageDetector extends Detector implements Detector.JavaScanner {
 
 public static final Issue ISSUE = ...;
 
 @Override
 public List<String> getApplicableMethodNames() {
 return Arrays.asList("v", "d", "i", "w", "e", "wtf");
 }
 
 @Override
 public void visitMethod(@NonNull JavaContext context, 
 AstVisitor visitor, 
 @NonNull MethodInvocation node) {
 if (!(node.astOperand() instanceof VariableReference)) {
 return;
 }
 VariableReference ref = (VariableReference) node.astOperand();
 if ("Log".equals(ref.astIdentifier().astValue())) {
 context.report(ISSUE,
 node,
 context.getLocation(node),
 "Using 'Log' instead of 'Timber'");
 }
 }
 }
15. Issue • potential bug in an Android application • is discovered by a Detector • are exposed to the user public static final Issue ISSUE = Issue.create("LogNotTimber",
 "Used Log instead of Timber",
 "Since Timber is included in the project, " + "it is likely that calls to Log should "
 + "instead be going to Timber.",
 Category.MESSAGES,
 5,
 Severity.WARNING,
 new Implementation(WrongTimberUsageDetector.class, Scope.JAVA_FILE_SCOPE));
16. Issue • the id of the issue • should be unique • recommended to add the package name as a prefix like com.wire.LogNotTimber public static final Issue ISSUE = Issue.create(“LogNotTimber", "Used Log instead of Timber",
 "Since Timber is included in the project, “ + "it is likely that calls to Log should "
 + "instead be going to Timber.",
 Category.MESSAGES,
 5,
 Severity.WARNING,
 new Implementation(WrongTimberUsageDetector.class, Scope.JAVA_FILE_SCOPE));
17. Issue • the id of the issue • short summary • typically 5-6 words or less • describe the problem rather than the fix public static final Issue ISSUE = Issue.create(“LogNotTimber", "Used Log instead of Timber",
 "Since Timber is included in the project, “ + "it is likely that calls to Log should "
 + "instead be going to Timber.",
 Category.MESSAGES,
 5,
 Severity.WARNING,
 new Implementation(WrongTimberUsageDetector.class, Scope.JAVA_FILE_SCOPE));
18. Issue • the id of the issue • short summary • full explanation of the issue • should include a suggestion how to fix it public static final Issue ISSUE = Issue.create(“LogNotTimber", "Used Log instead of Timber",
 "Since Timber is included in the project, “ + "it is likely that calls to Log should "
 + "instead be going to Timber.",
 Category.MESSAGES,
 5,
 Severity.WARNING,
 new Implementation(WrongTimberUsageDetector.class, Scope.JAVA_FILE_SCOPE));
19. Issue • the id of the issue • short summary • full explanation of the issue • the associated category, if any • Lint • Correctness (incl. Messages) • Security • Performance • Usability (incl. Icons, Typography) • Accessibility • Internationalization • Bi-directional text public static final Issue ISSUE = Issue.create(“LogNotTimber", "Used Log instead of Timber",
 "Since Timber is included in the project, “ + "it is likely that calls to Log should "
 + "instead be going to Timber.",
 Category.MESSAGES,
 5,
 Severity.WARNING,
 new Implementation(WrongTimberUsageDetector.class, Scope.JAVA_FILE_SCOPE));
20. Issue • the id of the issue • short summary • full explanation of the issue • the associated category, if any • the priority • a number from 1 to 10 • 10 being most important/severe public static final Issue ISSUE = Issue.create(“LogNotTimber", "Used Log instead of Timber",
 "Since Timber is included in the project, “ + "it is likely that calls to Log should "
 + "instead be going to Timber.",
 Category.MESSAGES,
 5,
 Severity.WARNING,
 new Implementation(WrongTimberUsageDetector.class, Scope.JAVA_FILE_SCOPE));
21. Issue • the id of the issue • short summary • full explanation of the issue • the associated category, if any • the priority • the default severity of the issue • Fatal • Error • Warning • Informational • Ignore public static final Issue ISSUE = Issue.create(“LogNotTimber", "Used Log instead of Timber",
 "Since Timber is included in the project, “ + "it is likely that calls to Log should "
 + "instead be going to Timber.",
 Category.MESSAGES,
 5,
 Severity.WARNING,
 new Implementation(WrongTimberUsageDetector.class, Scope.JAVA_FILE_SCOPE));
22. Issue • the id of the issue • short summary • full explanation of the issue • the associated category, if any • the priority • the default severity of the issue • the default implementation for this issue • maps to the Detector class • specifies the scope of the implementation public static final Issue ISSUE = Issue.create(“LogNotTimber", "Used Log instead of Timber",
 "Since Timber is included in the project, “ + "it is likely that calls to Log should "
 + "instead be going to Timber.",
 Category.MESSAGES,
 5,
 Severity.WARNING,
 new Implementation(WrongTimberUsageDetector.class, Scope.JAVA_FILE_SCOPE));
23. Issue • the id of the issue • short summary • full explanation of the issue • the associated category, if any • the priority • the default severity of the issue • the default implementation for this issue • the scope of the implementation • describes set of files a detector must consider when performing its analysis • Include: • Resource files / folder • Java files • Class files public static final Issue ISSUE = Issue.create(“LogNotTimber", "Used Log instead of Timber",
 "Since Timber is included in the project, “ + "it is likely that calls to Log should "
 + "instead be going to Timber.",
 Category.MESSAGES,
 5,
 Severity.WARNING,
 new Implementation(WrongTimberUsageDetector.class, Scope.JAVA_FILE_SCOPE));
24. Issue Registry • provide list of checks to be performed • return a list of Issues in getIssues() public class CustomIssueRegistry extends IssueRegistry {
 @Override
 public List<Issue> getIssues() {
 return Arrays.asList(WrongTimberUsageDetector.ISSUE);
 }
 }
25. Include within your Project
26. Project structure • lintrules • Java module • source of all custom detectors and our IssueRegistry • specify reference in build.gradle as attribute Lint-Registry • will export a lint.jar $ ./gradlew projects :projects ------------------------------------------------------------ Root project ------------------------------------------------------------ Root project ‘awsm_app' +--- Project ':app' +--- Project ':lintlib' \--- Project ':lintrules' jar { manifest { attributes 'Manifest-Version': 1.0 attributes 'Lint-Registry': 'com.checks.CustomIssueRegistry' } }
27. Project structure • lintrules • lintlib • Android library module • has a dependency to lintrules $ ./gradlew projects :projects ------------------------------------------------------------ Root project ------------------------------------------------------------ Root project ‘awsm_app' +--- Project ':app' +--- Project ':lintlib' \--- Project ':lintrules'
28. Project structure • lintrules • lintlib • app • has dependency to lintlib module • since lintlib is an Android library module, we can use the generated lint.jar $ ./gradlew projects :projects ------------------------------------------------------------ Root project ------------------------------------------------------------ Root project ‘awsm_app' +--- Project ':app' +--- Project ':lintlib' \--- Project ':lintrules'
29. Project structure • lintrules • lintlib • app • check your project using with ./gradlew lint • configure Lint as described here: http://goo.gl/xABHhy $ ./gradlew projects :projects ------------------------------------------------------------ Root project ------------------------------------------------------------ Root project ‘awsm_app' +--- Project ':app' +--- Project ':lintlib' \--- Project ':lintrules'
30. Further information
31. Testing • part of lintrules module • tested with JUnit 4.12 and Easymock 3.3 • register and execute tests as usual in build.gradle public class WrongTimberUsageTest extends LintCheckTest {
 
 @Override
 protected Detector getDetector() {
 return new WrongTimberUsageDetector();
 }
 
 @Test
 public void testLog() throws Exception {
 String expected = ...;
 String lintResult = lintFiles(
 "WrongTimberTestActivity.java.txt=>" +
 "src/test/WrongTimberTestActivity.java");
 assertEquals(expectedResult, lintResult);
 }
 }
32. Testing • part of lintrules module • tested with JUnit 4.12 and Easymock 3.3 • register and execute tests as usual in build.gradle • every test should extend LintCheckTest • custom version of AbstractCheckTest public class WrongTimberUsageTest extends LintCheckTest {
 
 @Override
 protected Detector getDetector() {
 return new WrongTimberUsageDetector();
 }
 
 @Test
 public void testLog() throws Exception {
 String expected = ...;
 String lintResult = lintFiles(
 "WrongTimberTestActivity.java.txt=>" +
 "src/test/WrongTimberTestActivity.java");
 assertEquals(expectedResult, lintResult);
 }
 }
33. Testing • part of lintrules module • tested with JUnit 4.12 and Easymock 3.3 • register and execute tests as usual in build.gradle • every test should extend LintCheckTest • need to define the to be used detector and the selected issues public class WrongTimberUsageTest extends LintCheckTest {
 
 @Override
 protected Detector getDetector() {
 return new WrongTimberUsageDetector();
 }
 
 @Test
 public void testLog() throws Exception {
 String expected = ...;
 String lintResult = lintFiles(
 "WrongTimberTestActivity.java.txt=>" +
 "src/test/WrongTimberTestActivity.java");
 assertEquals(expectedResult, lintResult);
 }
 }
34. Testing • part of lintrules module • tested with JUnit 4.12 and Easymock 3.3 • register and execute tests as usual in build.gradle • every test should extend LintCheckTest • need to define the to be used detector and the selected issues • perform usual unit tests with the helper methods including: • lintFiles • lintProject public class WrongTimberUsageTest extends LintCheckTest {
 
 @Override
 protected Detector getDetector() {
 return new WrongTimberUsageDetector();
 }
 
 @Test
 public void testLog() throws Exception {
 String expected = ...;
 String lintResult = lintFiles(
 "WrongTimberTestActivity.java.txt=>" +
 "src/test/WrongTimberTestActivity.java");
 assertEquals(expectedResult, lintResult);
 }
 }
35. Testing • need to specify the files that should be tested • put into data/src package in test resources • append to all classes suffix .txt • more examples: https://goo.gl/Z3gk5U public class WrongTimberTestActivity extends FragmentActivity {
 
 private static final String TAG = "WrongTimberTestActivity";
 
 @Override
 protected void onCreate(Bundle savedInstanceState) {
 super.onCreate(savedInstanceState);
 setContentView(R.layout.main);
 Log.d(TAG, "Test android logging");
 Timber.d("Test timber logging");
 }
 }
36. Debugging • not possible on real sources without building lint on your own • workaround is to debug on your tests
37. Conclusion • not well documented API • sample project: https://goo.gl/TQt1jV • to improve code quality • help new team members
38. Questions?
39. Thank you!