WhiteSpaceWarrior 1.0.3
dotnet tool install --global WhiteSpaceWarrior --version 1.0.3
dotnet new tool-manifest # if you are setting up this repo dotnet tool install --local WhiteSpaceWarrior --version 1.0.3
#tool dotnet:?package=WhiteSpaceWarrior&version=1.0.3
nuke :add-package WhiteSpaceWarrior --version 1.0.3
WhiteSpaceWarrior
is a tool that make reading code significantly faster by improving the signal to noise ratio of the code. It
removes all the stuff you get anoyed about when you speed-read code, such as empty lines, empty comments, and short meaningles comments. In other words,
it removes noise.
The impact on code readbility when removing noise from the code
Let's illustrate the effect of a noisy code base. The example is perhaps not a 100% accurate representation of all code bases, however, I've accumulated all the different kinds
of code noise I've encountered in my career. It also show cases the capabilities of whitespacewarrior
.
/// <summary>
/// </summary>
public class Calculator
{
#region Properties
/// <summary>
/// Usage count
/// </summary>
private int CalculationCount
{
get;
set;
}
#endregion
#region Methods
/// <summary>
///
/// </summary>
/// <typeparam name=""T""></typeparam>
/// <param name=""a""></param>
/// <param name=""b""></param>
/// <returns></returns>
public int Add<T>(int a, int b)
{
CalculationCount++;
return a + b;
}
///////////////////////////////////////////////
/// <summary>
/// Minus impl
/// </summary>
/// <param name=""a"">A number</param>
/// <param name=""b"">A number</param>
/// <returns></returns>
public int Minus(int a, int b)
{
CalculationCount++;
return a - b;
}
#endregion
}
Let's reformat with whitespacewarrior
. Notice once all the noise is gone, how much easier it is to attain and keep focus.
The code is reduced from 49 lines to just 16 lines!
public class Calculator
{
private int CalculationCount { get; set; }
public int Add<T>(int a, int b)
{
CalculationCount++;
return a + b;
}
public int Minus(int a, int b)
{
CalculationCount++;
return a - b;
}
}
Here is a short summary of what kind of whitespace that is cleaned up:
- Empty lines around
{
and}
- Empty or short
<summary>
,<param name="..">
,<returns>
, ... - Shortening short
<summary>
down to 1 line from the standard 3 lines - Regions
#region
and#endregion
- Newlines around properties (getters, setters) and also reordering of properties so
get
is placed beforeset
.
Installation
> dotnet tool install --global WhiteSpaceWarrior
Then you can use the command WhiteSpaceWarrior
in your shell.
Or visit the releases at https://github.com/kbilsted/WhitespaceWarrior/releases
Code readability and catering for it
One thing that strikes me, is the different between reading a book and reading code. A book has a narative, emotional characters, page numbers and switches beteen building and releasing tension. Reading code, on the other hand, is about absorbing intent, building mental models in your mind. Often with great frustration when the code gets too complex.
When we read code, we use techniques ranging from scanning (fast-pased reading), to slow-pased scrutiny.
(code reading spectrum)
fast slow
<---------------------------------->
Scannning Scrutinizing
When discussing code readability, it often from the perspective slower-pased reading. I believe we do a great deal of scanning. My belief is rooted in a lot of facts
- Only source code is typeset with Mono-spaced fonts. Books, magazines , newspapers, etc. all use proportional fonts
- Most programmers have an oppinion and preference with regards to indentation size
- Most programmers prefer syntax highlighting with colours both in editors/IDE's and when reading code-oriented web pages
- People express diffculty in keeping concentration and focus when faced with code bases with large portions of text, that do not contribute meaning.
So faced with a large code base, how do you improve its readability? I think Effort is a key word here. Some code-improving actions require a lot of effort, others not so much.
With a tool like WhiteSpaceWarrior
we can process a very large code base and review all the changes within an hour! That will beat most other initiatives by magnitutes.
Of course, the same goes for the effect on the code base. An example of a low effort initiaitive is code formatting making the code base look simiar in terms of overall structure.
An example of a large effort initiative is ensuring test coverage, applying SRP, SOLID, FailFast, design patterns, introducing service orchestration and so on.
To visualize this we need two graphs. One for each end of the spectrum of our code reading strategies.
(scanning) (scrutinizing)
^ Effort ^ Effort
| |
| o TDD | o TDD
| |
| o Design patterns | o Design patterns
| |
| o SRP | o SRP
| |
| |
| |
| |
| |
| |
| |
| |
| o whitespacewarrior | o whitespacewarrior
-----+--------------------------> -----+-------------------------->
| Readability | Readability
| |
Obviously, reducing the amount of characters in a source code, makes scanning more effective, whereas code scrutiny is much less affected. I've compiled a set articles that deal with improving code readability here http://firstclassthoughts.co.uk/Tags/Code_Readability.html
Language support
At the moment only C# is supported.
However, I'm very interested in working toghether with people wanting whitespacewarrior-support for their favorite language!
Configuration
WhiteSpaceWarrior is very configurable
Usage: WhiteSpaceWarrior [options] <Path>
Arguments:
Path The path from which to recursively compress cs files
Options:
--version Show version information
-v|--verbosity <VERBOSITY> Set verbosity level
-rpn|--remove-param-name-upto-nwords <REMOVE_PARAM_NAME_UPTO_NWORDS> Remove <param name=".."> descriptions up to N words long. A low number such as "2" captures many useless comments.
-rsn|--remove-summary-upto-nwords <REMOVE_SUMMARY_UPTO_NWORDS> Remove <summary> descriptions up to N words long. A low number such as "2" captures many useless comments.
-rr|--remove-regions Remove #region
-rt|--remove-tags <REMOVE_TAGS> Remove <tag> in ///-sections. Can be specified multiple times
-nl|--no-logo Don't show logo
-?|-h|--help Show help information
Testing
Install as a power tool locally from a local build
> dotnet tool install --add-source C:\src\WhitespaceWarrior\WhiteSpaceWarrior\bin\Debug\ --tool-path tools WhiteSpaceWarrior
and then
> .\tools\WhiteSpaceWarrior.exe --help
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
This package has no dependencies.