Omit Needless Words
To promote clear usage, the Swift API Design Guidelines advice that we omit needless words in function names. Words that merely repeat type information are specifically identified as needless.
This is a tool that helps you spot those words in your code base.
Install
Prerequisite: have Swift 3 installed on your system.
- Clone or download content of this repository.
- run
make
.
Usage
Basic
The command needless
can process text from STDIN or files specified in a list of
paths. The simplest way to use it is one of the following:
needless path/to/file1.swift path/to/file2.swift
echo "func someName(foo bar: Baz..." | needless
needless
will print out function names with needless words and suggest an
alternative.
Run needless -h
for more details, or read the next section.
Options
Several output formats are included for different use scenarios. They make this command more useful when combined with other scripts/tools.
-
By default,
needless
prints output in a readable format:potential needless words in first parameter label in path/to/file.swift (line 87) private func buttonTitleColor(forType type: NewsfeedItemType) -> UIColor { ^ possible alternative: func buttonTitleColor(for type: NewsfeedItemType …
-
Use the option
-Xcode
forclang
/swiftc
style warning:needless -Xcode path/to/file.swift
path/to/file.swift:23:5: warning: potential needless words in function name 'func testWithData(_ data: Data …'; perhaps use 'func test(with data: Data …' instead?
This means you can add
needless
as a build phase in Xcode to get inline highlighting.-
add a "Run Script" build phase in your Xcode project and paste in the following:
needless -dollar path/to/file.swift
IFS=$'\n' find . -name "*.swift" -exec needless -Xcode {} \;
(customize the command according to your needs. e.g. you may want to change the path
.
toSources
to avoid warnings for files inPackages
orPods
folder). -
build your Xcode project.
-
-
-dollar
prints results in$
-separated strings:needless -dollar path/to/file.swift
potential needless words in function name$path/to/file.swift$22$4$func testWithData(_ data: Data$func test(with data: Data
That's
[description]$[path]$[line number]$[column number]$[original name]$[suggested name]
This format is convenient for parsing and further actions. It's trivial to read it and do automated replacement, for example.
-
-diff
will makeneedless
only process lines that begin with character+
,!
or>
. This is handy when you are dealing with patch formats. Makeneedless
part of your git hooks!-diff
can be combined with-dollar
and-Xcode
.
Not a robot
The API guideline starts with "every word in a name should convey salient
information at the use site". needless
isn't AI with advanced natural
language processing capabilities (yet?). In fact, it assumes you use camelCase
in function names and merely tries to find problematic function names in a very
mechanical (dumb) way. Its suggestions are often awkward/too aggressive. Always
prioritize good human judgement please :)