rust/README.md

#rust-clippy

A collection of lints to catch common mistakes and improve your Rust code.

Table of contents:

• Lint list
• Usage instructions
• Configuration
• clippy-service
• License

##Lints There are 139 lints included in this crate:

name	default	meaning
absurd_extreme_comparisons	warn	a comparison involving a maximum or minimum value involves a case that is always true or always false
almost_swapped	warn	foo = bar; bar = foo sequence
approx_constant	warn	the approximate of a known float constant (in std::f64::consts or std::f32::consts) is found; suggests to use the constant
bad_bit_mask	warn	expressions of the form _ & mask == select that will only ever return true or false (because in the example select containing bits that mask doesn't have)
blacklisted_name	warn	usage of a blacklisted/placeholder name
block_in_if_condition_expr	warn	braces can be eliminated in conditions that are expressions, e.g if { true } ...
block_in_if_condition_stmt	warn	avoid complex blocks in conditions, instead move the block higher and bind it with 'let'; e.g: if { let x = true; x } ...
bool_comparison	warn	comparing a variable to a boolean, e.g. if x == true
box_vec	warn	usage of Box<Vec<T>>, vector elements are already on the heap
boxed_local	warn	using Box where unnecessary
cast_possible_truncation	allow	casts that may cause truncation of the value, e.g x as u8 where x: u32, or x as i32 where x: f32
cast_possible_wrap	allow	casts that may cause wrapping around the value, e.g x as i32 where x: u32 and x > i32::MAX
cast_precision_loss	allow	casts that cause loss of precision, e.g x as f32 where x: u64
cast_sign_loss	allow	casts from signed types to unsigned types, e.g x as u32 where x: i32
char_lit_as_u8	warn	Casting a character literal to u8
chars_next_cmp	warn	using .chars().next() to check if a string starts with a char
clone_double_ref	warn	using clone on &&T
clone_on_copy	warn	using clone on a Copy type
cmp_nan	deny	comparisons to NAN (which will always return false, which is probably not intended)
cmp_owned	warn	creating owned instances for comparing with others, e.g. x == "foo".to_string()
collapsible_if	warn	two nested if-expressions can be collapsed into one, e.g. if x { if y { foo() } } can be written as if x && y { foo() } and an else { if .. } expression can be collapsed to else if`
crosspointer_transmute	warn	transmutes that have to or from types that are a pointer to the other
cyclomatic_complexity	warn	finds functions that should be split up into multiple functions
deprecated_semver	warn	Warn on #[deprecated(since = "x")] where x is not semver
derive_hash_xor_eq	warn	deriving Hash but implementing PartialEq explicitly
doc_markdown	warn	checks for the presence of _, :: or camel-case outside ticks in documentation
drop_ref	warn	call to std::mem::drop with a reference instead of an owned value, which will not call the Drop::drop method on the underlying value
duplicate_underscore_argument	warn	Function arguments having names which only differ by an underscore
empty_loop	warn	empty loop {} detected
enum_clike_unportable_variant	warn	finds C-like enums that are repr(isize/usize) and have values that don't fit into an i32
enum_glob_use	allow	finds use items that import all variants of an enum
enum_variant_names	warn	finds enums where all variants share a prefix/postfix
eq_op	warn	equal operands on both sides of a comparison or bitwise combination (e.g. x == x)
expl_impl_clone_on_copy	warn	implementing Clone explicitly on Copy types
explicit_counter_loop	warn	for-looping with an explicit counter when _.enumerate() would do
explicit_iter_loop	warn	for-looping over _.iter() or _.iter_mut() when &_ or &mut _ would do
extend_from_slice	warn	.extend_from_slice(_) is a faster way to extend a Vec by a slice
filter_next	warn	using filter(p).next(), which is more succinctly expressed as .find(p)
float_cmp	warn	using == or != on float values (as floating-point operations usually involve rounding errors, it is always better to check for approximate equality within small bounds)
for_kv_map	warn	looping on a map using iter when keys or values would do
for_loop_over_option	warn	for-looping over an Option, which is more clearly expressed as an if let
for_loop_over_result	warn	for-looping over a Result, which is more clearly expressed as an if let
identity_op	warn	using identity operations, e.g. x + 0 or y / 1
if_not_else	warn	finds if branches that could be swapped so no negation operation is necessary on the condition
if_same_then_else	warn	if with the same then and else blocks
ifs_same_cond	warn	consecutive ifs with the same condition
indexing_slicing	allow	indexing/slicing usage
ineffective_bit_mask	warn	expressions where a bit mask will be rendered useless by a comparison, e.g. `(x
inline_always	warn	#[inline(always)] is a bad idea in most cases
invalid_regex	deny	finds invalid regular expressions in Regex::new(_) invocations
items_after_statements	warn	finds blocks where an item comes after a statement
iter_next_loop	warn	for-looping over _.next() which is probably not intended
len_without_is_empty	warn	traits and impls that have .len() but not .is_empty()
len_zero	warn	checking .len() == 0 or .len() > 0 (or similar) when .is_empty() could be used instead
let_and_return	warn	creating a let-binding and then immediately returning it like let x = expr; x at the end of a block
let_unit_value	warn	creating a let binding to a value of unit type, which usually can't be used afterwards
linkedlist	warn	usage of LinkedList, usually a vector is faster, or a more specialized data structure like a VecDeque
logic_bug	warn	checks for boolean expressions that contain terminals which can be eliminated
manual_swap	warn	manual swap
many_single_char_names	warn	too many single character bindings
map_clone	warn	using `.map(
map_entry	warn	use of contains_key followed by insert on a HashMap or BTreeMap
match_bool	warn	a match on boolean expression; recommends if..else block instead
match_overlapping_arm	warn	a match has overlapping arms
match_ref_pats	warn	a match or if let has all arms prefixed with &; the match expression can be dereferenced instead
match_same_arms	warn	match with identical arm bodies
min_max	warn	min(_, max(_, _)) (or vice versa) with bounds clamping the result to a constant
modulo_one	warn	taking a number modulo 1, which always returns 0
mut_mut	allow	usage of double-mut refs, e.g. &mut &mut ... (either copy'n'paste error, or shows a fundamental misunderstanding of references)
mutex_atomic	warn	using a Mutex where an atomic value could be used instead
mutex_integer	allow	using a Mutex for an integer type
needless_bool	warn	if-statements with plain booleans in the then- and else-clause, e.g. if p { true } else { false }
needless_lifetimes	warn	using explicit lifetimes for references in function arguments when elision rules would allow omitting them
needless_range_loop	warn	for-looping over a range of indices where an iterator over items would do
needless_return	warn	using a return statement like return expr; where an expression would suffice
needless_update	warn	using { ..base } when there are no missing fields
new_ret_no_self	warn	not returning Self in a new method
new_without_default	warn	fn new() -> Self method without Default implementation
no_effect	warn	statements with no effect
non_ascii_literal	allow	using any literal non-ASCII chars in a string literal; suggests using the \u escape instead
nonminimal_bool	warn	checks for boolean expressions that can be written more concisely
nonsensical_open_options	warn	nonsensical combination of options for opening a file
ok_expect	warn	using ok().expect(), which gives worse error messages than calling expect directly on the Result
option_map_unwrap_or	warn	using Option.map(f).unwrap_or(a), which is more succinctly expressed as map_or(a, f)
option_map_unwrap_or_else	warn	using Option.map(f).unwrap_or_else(g), which is more succinctly expressed as map_or_else(g, f)
option_unwrap_used	allow	using Option.unwrap(), which should at least get a better message using expect()
or_fun_call	warn	using any *or method when the *or_else would do
out_of_bounds_indexing	deny	out of bound constant indexing
overflow_check_conditional	warn	Using overflow checks which are likely to panic
panic_params	warn	missing parameters in panic!
precedence	warn	catches operations where precedence may be unclear. See the wiki for a list of cases caught
print_stdout	allow	printing on stdout
ptr_arg	warn	fn arguments of the type &Vec<...> or &String, suggesting to use &[...] or &str instead, respectively
range_step_by_zero	warn	using Range::step_by(0), which produces an infinite iterator
range_zip_with_len	warn	zipping iterator with a range when enumerate() would do
redundant_closure	warn	using redundant closures, i.e. `
redundant_closure_call	warn	Closures should not be called in the expression they are defined
redundant_pattern	warn	using name @ _ in a pattern
regex_macro	warn	finds use of regex!(_), suggests Regex::new(_) instead
result_unwrap_used	allow	using Result.unwrap(), which might be better handled
reverse_range_loop	warn	Iterating over an empty range, such as 10..0 or 5..5
search_is_some	warn	using an iterator search followed by is_some(), which is more succinctly expressed as a call to any()
shadow_reuse	allow	rebinding a name to an expression that re-uses the original value, e.g. let x = x + 1
shadow_same	allow	rebinding a name to itself, e.g. let mut x = &mut x
shadow_unrelated	allow	The name is re-bound without even using the original value
should_implement_trait	warn	defining a method that should be implementing a std trait
similar_names	warn	similarly named items and bindings
single_char_pattern	warn	using a single-character str where a char could be used, e.g. _.split("x")
single_match	warn	a match statement with a single nontrivial arm (i.e, where the other arm is _ => {}) is used; recommends if let instead
single_match_else	allow	a match statement with a two arms where the second arm's pattern is a wildcard; recommends if let instead
string_add	allow	using x + .. where x is a String; suggests using push_str() instead
string_add_assign	allow	using x = x + .. where x is a String; suggests using push_str() instead
string_lit_as_bytes	warn	calling as_bytes on a string literal; suggests using a byte string literal instead
suspicious_assignment_formatting	warn	suspicious formatting of *=, -= or !=
suspicious_else_formatting	warn	suspicious formatting of else if
temporary_assignment	warn	assignments to temporaries
too_many_arguments	warn	functions with too many arguments
toplevel_ref_arg	warn	An entire binding was declared as ref, in a function argument (fn foo(ref x: Bar)), or a let statement (let ref x = foo()). In such cases, it is preferred to take references with &.
transmute_ptr_to_ref	warn	transmutes from a pointer to a reference type
trivial_regex	warn	finds trivial regular expressions in Regex::new(_) invocations
type_complexity	warn	usage of very complex types; recommends factoring out parts into type definitions
unicode_not_nfc	allow	using a unicode literal not in NFC normal form (see http://www.unicode.org/reports/tr15/ for further information)
unit_cmp	warn	comparing unit values (which is always true or false, respectively)
unnecessary_mut_passed	warn	an argument is passed as a mutable reference although the function/method only demands an immutable reference
unneeded_field_pattern	warn	Struct fields are bound to a wildcard instead of using ..
unused_collect	warn	collect()ing an iterator without using the result; this is usually better written as a for loop
unused_label	warn	unused label
unused_lifetimes	warn	unused lifetimes in function definitions
use_debug	allow	use Debug-based formatting
used_underscore_binding	warn	using a binding which is prefixed with an underscore
useless_format	warn	useless use of format!
useless_transmute	warn	transmutes that have the same to and from types
useless_vec	warn	useless vec!
while_let_loop	warn	loop { if let { ... } else break } can be written as a while let loop
while_let_on_iterator	warn	using a while-let loop instead of a for loop on an iterator
wrong_pub_self_convention	allow	defining a public method named with an established prefix (like "into_") that takes self with the wrong convention
wrong_self_convention	warn	defining a method named with an established prefix (like "into_") that takes self with the wrong convention
zero_divided_by_zero	warn	usage of 0.0 / 0.0 to obtain NaN instead of std::f32::NaN or std::f64::NaN
zero_width_space	deny	using a zero-width space in a string literal, which is confusing

More to come, please file an issue if you have ideas!

##Usage

Compiler plugins are highly unstable and will only work with a nightly Rust for now. Since stable Rust is backwards compatible, you should be able to compile your stable programs with nightly Rust with clippy plugged in to circumvent this.

Add in your Cargo.toml:

[dependencies]
clippy = "*"

You then need to add #![feature(plugin)] and #![plugin(clippy)] to the top of your crate entry point (main.rs or lib.rs).

Sample main.rs:

#![feature(plugin)]

#![plugin(clippy)]


fn main(){
    let x = Some(1u8);
    match x {
        Some(y) => println!("{:?}", y),
        _ => ()
    }
}

Produces this warning:

src/main.rs:8:5: 11:6 warning: you seem to be trying to use match for destructuring a single type. Consider using `if let`, #[warn(single_match)] on by default
src/main.rs:8     match x {
src/main.rs:9         Some(y) => println!("{:?}", y),
src/main.rs:10         _ => ()
src/main.rs:11     }
src/main.rs:8:5: 11:6 help: Try
if let Some(y) = x { println!("{:?}", y) }

An alternate way to use clippy is by compiling and using cargo clippy, a custom cargo subcommand that runs clippy on a given project.

You can add options to allow/warn/deny:

• the whole set of Warn lints using the clippy lint group (#![deny(clippy)])
• all lints using both the clippy and clippy_pedantic lint groups (#![deny(clippy)], #![deny(clippy_pedantic)]). Note that clippy_pedantic contains some very aggressive lints prone to false positives.
• only some lints (#![deny(single_match, box_vec)], etc)
• allow/warn/deny can be limited to a single function or module using #[allow(...)], etc

Note: deny produces errors instead of warnings

To have cargo compile your crate with clippy without needing #![plugin(clippy)] in your code, you can use:

cargo rustc -- -L /path/to/clippy_so -Z extra-plugins=clippy

Note: Be sure that clippy was compiled with the same version of rustc that cargo invokes here!

If you want to make clippy an optional dependency, you can do the following:

In your Cargo.toml:

[dependencies]
clippy = {version = "*", optional = true}

[features]
default=[]

And, in your main.rs or lib.rs:

#![cfg_attr(feature="clippy", feature(plugin))]

#![cfg_attr(feature="clippy", plugin(clippy))]

Instead of adding the cfg_attr attributes you can also run clippy on demand: cargo rustc --features clippy -- -Z no-trans -Z extra-plugins=clippy (the -Z no trans, while not neccessary, will stop the compilation process after typechecking (and lints) have completed, which can significantly reduce the runtime).

Configuration

Some lints can be configured in a clippy.toml file. It contains basic variable = value mapping eg.

blacklisted-names = ["toto", "tata", "titi"]
cyclomatic-complexity-threshold = 30

See the wiki for more information about which lints can be configured and the meaning of the variables.

You can also specify the path to the configuration file with:

#![plugin(clippy(conf_file="path/to/clippy's/configuration"))]

##Link with clippy service clippy-service is a rust web initiative providing rust-clippy as a web service.

Both projects are independent and maintained by different people (even if some clippy-service's contributions are authored by some rust-clippy members).

You can check it out this great service at clippy.bashy.io.

##License Licensed under MPL. If you're having issues with the license, let me know and I'll try to change it to something more permissive.