Compilers Don't Care but Humans Do
Well formatted code makes it easier for humans to read and navigate. Many languages (including C#, the primary language I'm using these days) don't care about white space.
That means that this method is perfectly valid C#:
Ack! This code compiles and runs just fine. But it's very difficult to read.
Note: This code is taken from "I'll Get Back to You: Task, Await, and Asynchronous Methods". The source is on Github: https://github.com/jeremybytes/using-task.
Format Document to the Rescue!
Fortunately, Visual Studio can fix this. All we need to do is find the "Format Document" option on the Edit menu:
This is under Edit -> Advanced -> Format Document.
You can see the keyboard shortcut listed here is Ctrl+E, D, but Ctrl+K, D also works. There's a pretty extensive list of shortcuts listed here: http://visualstudioshortcuts.com/2015/
Once we "Format Document", things are much easier to read:
Much better!
Controlling Formatting
I generally stick with the default formatting for C#. But if we don't like the defaults, they're pretty easy to change. For this, we look at Tools -> Options.
These are in the tree under Text Editor -> C# -> Formatting. (And of course, we can have different settings for other languages and file types.)
One thing that I like about this dialog is that it gives previews to help us make the selections. For example, let's look at the "Indentation" option. If we select "Indent open and close braces", we see a preview in the bottom half of the pane:
If we check the box, the preview updates:
This lets us see what the code will look like if we select any particular option. And the code samples are different for each option. This makes sure we have a relevant block of code for whatever option we chose.
It can get a little confusing because we can check boxes without selecting the option in the list. In this case, the preview pane doesn't always update. So I would suggest clicking on the item itself before checking/unchecking the box.
Lots of Options
There are a ton of different options. For example, what if we want to take full control over where the opening curly braces go. Here are just a few of the options under "New Lines":
In this case, we always want to have opening braces on their own line (which is my preference), but we can choose individual items if we want something different -- this would let us implement the K&R style (although I don't recommend that).
And when we dig into options a bit more, we see that we have the choice to leave block elements on a single line (meaning, the opening and closing brace are on the same line). Or we can always expand those to multiple lines.
The customization is a little overwhelming, but it's nice to have the flexibility to auto-format the code the way we want.
Sharing Format Options
If we're working alone, it doesn't really matter what formatting options we choose. But once we start to get into a shared environment, Things are a bit different.
For example, if I prefer to have my code formatted differently than my co-worker, we'll end up with a mess in our source control. That's because if we make formatting changes, our diff tools can't always pick out the changes that impact the code and the ones that are simply formatting. So generally, it's best to have a format that everyone agrees on (or run things through a shared formatter before checking in).
To share options with the team (or even just between different computers), we can export our settings. From the Tools menu, just select "Import and Export Settings...":
Then follow the steps in the wizard to save off a file or load a file. When exporting, we can even choose which items we want to include:
This lets us create a file that only has Formatting options. Then when we import it, we only get those particular settings.
Format Document is not Perfect
"Format Document" is really awesome, but it's not quite perfect. It would be nice if Visual Studio could read my mind (actually, that might be kind of frightening -- never mind).
Sometimes we have to do some manual formatting. But it's still pretty easy to do. For this example, we'll look at a lambda expression:
Again, the compiler doesn't care about the formatting of this code, but the humans do.
Note: This is the code that is seen in "Anatomy of a Lambda Expression".
If we use "Format Document" here, I don't quite get the results that I want:
You might say, "That looks okay." But it gets a little more obvious once I move the parameters "(s, e) =>" to the next line.
These are indented a level. And this is actually what I want since this is a continuation of the original assignment statement. But using "Format Document" here doesn't change anything. The indentation for the lambda expression stays the same. But there's a pretty easy workaround.
We'll start by highlighting the lines we want to indent:
And then press "Tab". This will indent the entire block (And we can use "Shift+Tab" to un-indent):
This is what I want.
We'll get similar results when we use class initializers and some other constructs. So it's good to keep this in the back of our minds.
Wrap Up
Visual Studio is a full-featured development environment. There are many shortcuts and helpers that let me focus on the code and quickly perform otherwise tedious tasks.
Formatting code is critical for human readability. For the most part, Visual Studio will format the code as you type it in or paste it in (also customizable under the Formatting options). Sometimes, we want to quickly get a code file into shape. For that, "Format Document" works great.
Happy Coding!
No comments:
Post a Comment