New linter for complex conditional expressions

DESCRIPTION

@@ -80,6 +80,7 @@ Collate:
     'commas_linter.R'
     'commented_code_linter.R'
     'comparison_negation_linter.R'
+    'complex_conditional_linter.R'
     'condition_call_linter.R'
     'condition_message_linter.R'
     'conjunct_test_linter.R'

NAMESPACE

@@ -33,6 +33,7 @@ export(coalesce_linter)
 export(commas_linter)
 export(commented_code_linter)
 export(comparison_negation_linter)
+export(complex_conditional_linter)
 export(condition_call_linter)
 export(condition_message_linter)
 export(conjunct_test_linter)

NEWS.md

@@ -79,6 +79,10 @@
 * The description in `?paste_linter` of `allow_file_path=` has been corrected (#2675, @MichaelChirico). In particular, `allow_file_path="never"` is the most strict form, `allow_file_path="always"` is the most lax form.
 * `comment_token` is removed from settings. This was a vestige of the now-defunct support for posting GitHub comments.
 
+## New linters
+
+* `complex_conditional_linter()` for encouraging refactoring of complex conditional expressions (like `if (x > 0 && y < 0 || z == 0)`) via well-named abstractions (#2676, @IndrajeetPatil).
+
 # lintr 3.2.0
 
 ## Deprecations & breaking changes
@@ -164,6 +168,7 @@
 * `pipe_return_linter()` for discouraging usage of `return()` inside a {magrittr} pipeline (part of #884, @MichaelChirico).
 * `one_call_pipe_linter()` for discouraging one-step pipelines like `x |> as.character()` (#2330 and part of #884, @MichaelChirico).
 * `object_overwrite_linter()` for discouraging re-use of upstream package exports as local variables (#2344, #2346 and part of #884, @MichaelChirico and @AshesITR).
+* `complex_conditional_linter()` for encouraging refactoring of complex conditional expressions (like `if (x > 0 && y < 0 || z == 0)`) via well-named abstractions (#2676, @IndrajeetPatil).
 
 ### Lint accuracy fixes: removing false positives
 

R/complex_conditional_linter.R

@@ -0,0 +1,111 @@
+#' Complex Conditional Expressions Linter
+#'
+#' Detects complex conditional expressions and suggests extracting
+#' them into Boolean functions or variables for improved readability and reusability.
+#'
+#' For example, if you have a conditional expression with more than two logical operands,
+#'
+#' ```
+#' if (looks_like_a_duck(x) &&
+#'     swims_like_a_duck(x) &&
+#'     quacks_like_a_duck(x)) {
+#'     ...
+#' }
+#' ````
+#'
+#' to improve its readability and reusability, you can extract the conditional expression.
+#'
+#' You can either extract it into a Boolean function:
+#'
+#' ```
+#' is_duck <- function(x) {
+#'   looks_like_a_duck(x) &&
+#'     swims_like_a_duck(x) &&
+#'     quacks_like_a_duck(x)
+#' }
+#'
+#' if (is_duck(x)) {
+#'   ...
+#' }
+#' ```
+#'
+#' or into a Boolean variable:
+#'
+#' ```
+#' is_duck <- looks_like_a_duck(x) &&
+#'    swims_like_a_duck(x) &&
+#'    quacks_like_a_duck(x)
+#'
+#' if (is_duck) {
+#'  ...
+#' }
+#' ```
+#'
+#' In addition to improving code readability, extracting complex conditional expressions
+#' has the added benefit of introducing a reusable abstraction.
+#'
+#' @param threshold Integer. The maximum number of logical operators (`&&` or `||`)
+#'   allowed in a conditional expression. The default is `2L`, meaning any conditional expression
+#'   with more than two logical operators will be flagged.
+#'
+#' @examples
+#' # will produce lints
+#' code <- "if (a && b && c) { do_something() }"
+#' writeLines(code)
+#' lint(
+#'   text = code,
+#'   linters = complex_conditional_linter()
+#' )
+#'
+#' # okay
+#' code <- "if (ready_to_do_something) { do_something() }"
+#' writeLines(code)
+#' lint(
+#'   text = code,
+#'   linters = complex_conditional_linter()
+#' )
+#'
+#' code <- "if (a && b && c) { do_something() }"
+#' writeLines(code)
+#' lint(
+#'   text = code,
+#'   linters = complex_conditional_linter(threshold = 2L)
+#' )
+#'
+#' @evalRd rd_tags("complex_conditional_linter")
+#' @seealso [linters] for a complete list of linters available in lintr.
+#' @export
+complex_conditional_linter <- function(threshold = 2L) {
+  stopifnot(is.numeric(threshold), length(threshold) == 1L, threshold >= 1L)
+  threshold <- as.integer(threshold)
+
+  xpath <- glue::glue("//expr[
+    parent::expr[IF or WHILE]
+    and
+    preceding-sibling::*[1][self::OP-LEFT-PAREN]
+    and
+    following-sibling::*[1][self::OP-RIGHT-PAREN]
+    and
+    count(descendant-or-self::*[AND2 or OR2]) > {threshold}
+  ]")
+
+
+  Linter(linter_level = "expression", function(source_expression) {
+    xml <- source_expression$xml_parsed_content
+
+    nodes <- xml2::xml_find_all(xml, xpath)
+
+    lints <- xml_nodes_to_lints(
+      nodes,
+      source_expression = source_expression,
+      lint_message = paste0(
+        "Complex conditional with more than ",
+        threshold,
+        " logical operator(s). Consider extracting into a boolean function or variable for readability and reusability."
+      ),
+      type = "warning"
+    )
+
+    lints
+  })
+}

R/get_source_expressions.R

@@ -82,6 +82,7 @@ get_source_expressions <- function(filename, lines = NULL) {
   names(source_expression$lines) <- seq_along(source_expression$lines)
   source_expression$content <- get_content(source_expression$lines)
   parsed_content <- get_source_expression(source_expression, error = function(e) lint_parse_error(e, source_expression))
+  is_unreliable_lint <- is_lint(e) && (is.na(e$line) || !nzchar(e$line) || e$message == "unexpected end of input")
 
   # Currently no way to distinguish the source of the warning
   #   from the message itself, so we just grep the source for the
@@ -90,7 +91,7 @@ get_source_expressions <- function(filename, lines = NULL) {
   # See https://bugs.r-project.org/show_bug.cgi?id=18863.
   w <- lint_parse_warnings(w, parsed_content, source_expression)
 
-  if (is_lint(e) && (is.na(e$line) || !nzchar(e$line) || e$message == "unexpected end of input")) {
+  if (is_unreliable_lint) {
     # Don't create expression list if it's unreliable (invalid encoding or unhandled parse error)
     return(list(expressions = list(), error = e, warning = w, lines = source_expression$lines))
   }

R/unnecessary_nesting_linter.R

@@ -284,7 +284,7 @@ unnecessary_nesting_linter <- function(
     unnecessary_else_brace_lints <- xml_nodes_to_lints(
       unnecessary_else_brace_expr,
       source_expression = source_expression,
-      lint_message = "Simplify this condition by using 'else if' instead of 'else { if.",
+      lint_message = "Simplify this condition by using 'else if' instead of 'else { if'.",
       type = "warning"
     )
 

inst/lintr/linters.csv

@@ -11,6 +11,7 @@ coalesce_linter,readability consistency best_practices
 commas_linter,style readability default configurable
 commented_code_linter,style readability best_practices default
 comparison_negation_linter,readability consistency
+complex_conditional_linter,style readability best_practices configurable
 condition_call_linter,style tidy_design best_practices configurable
 condition_message_linter,best_practices consistency
 conjunct_test_linter,package_development best_practices readability configurable pkg_testthat

lintr.Rproj

@@ -1,4 +1,5 @@
 Version: 1.0
+ProjectId: ab4c2695-5b43-4cc6-8ea0-0daf83afd8a3
 
 RestoreWorkspace: No
 SaveWorkspace: No