Skip to content

Update coding guidelines for control statement formatting #6904

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Nigusu-Allehu wants to merge 2 commits into from
Closed

Update coding guidelines for control statement formatting #6904

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
54646e1
Update coding guidelines for control statement formatting
Nigusu-Allehu Oct 27, 2025
7e91d74
Less strict
Nigusu-Allehu Oct 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 65 additions & 9 deletions docs/coding-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,25 +44,81 @@ The general rule we follow is "use Visual Studio defaults".

1. Avoid more than one empty line at any time. For example, do not have two blank lines between members of a type.

1. Add a blank line before control statements such as `if`, `for`, and `while` loops.
For readability, ensure there is a space ahead of these statements. For example:
1. When it helps readability, add a blank line before control flow statements such as `if`, `for`, or `while` loops to make the code’s structure easier to follow.

For example:

```csharp
statement1
statement2
// Less readable
int score = 85;
int highScore = 90;
bool isNewRecord = false;
if (score > highScore){
Console.WriteLine("New high score!");
isNewRecord = true;
}
if (isNewRecord){
Console.WriteLine("Congratulations!");
}else{
Copy link
Contributor

@jebriede jebriede Oct 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This example introduces a different issue than what the proposal is talking about. The issue of brace placement and spacing between braces should not be part of this example and should be demonstrated separately in a different coding guideline.

Console.WriteLine("Try again to beat the high score.");
}

if (...)
```

Blank lines make it easier for readers to see where one group of statements ends and another begins.
Copy link
Contributor

@jebriede jebriede Oct 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In some cases, this is true. In others, I disagree as I mentioned in our meeting yesterday. In some cases, a statement and a control block serve as a group of code that is best read when together, without excessive blank spaces, such as in this contrived code example:

public int CalculateScore(int points, int modifier)
{
    List<Player> activePlayers = GetActivePlayers();
    if (activePlayers.Count == 0)
    {
        return -1;
    }

    int score = points * modifier;
    if (score > 1000) {
        score = 1000; // score capped at 1000.
    }

    return score;
}

Copy link
Contributor

@jebriede jebriede Oct 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do agree with having a blank space between control blocks. This can be handled with a coding guideline (and analyzer) to ensure that there is a blank line after every control block unless that next line is a curly brace closing another block.


```csharp
// more readable
int score = 85;
int highScore = 90;
bool isNewRecord = false;

if (score > highScore)
{
Console.WriteLine("New high score!");
isNewRecord = true;
}

// Not:
statement1
statement2
if (...)
if (isNewRecord)
{
Console.WriteLine("Congratulations!");
}
else
{
Console.WriteLine("Try again to beat the high score.");
}
```
Use blank lines only when they clarify structure, not automatically before every statement.

For example:

Don't
```csharp
// Blank spaces do not help readability
for (int i = 0; i < 5; i++)
{

if (i % 2 == 0)
{

Console.WriteLine($"{i} is even.");

}
Copy link
Contributor

@jebriede jebriede Oct 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like this is the only "Don't" example: a time when blank lines would not be appropriate. However, this example introduces blank lines in the middle of the code block which is not part of the proposed guideline so it's showing an example that isn't an exception to the proposal. The proposed guideline is to put spaces before a control block separating any statements above it.


}
```

Do
```csharp
for (int i = 0; i < 5; i++)
{
if (i % 2 == 0)
{
Console.WriteLine($"{i} is even.");
}
}
```

1. Avoid lines of code longer than 120 characters.

1. Avoid spurious free spaces. For example avoid `if (someVar == 0)...`, where the dots mark the spurious free spaces. Consider enabling "View White Space (Ctrl+R, Ctrl+W)" or "Edit -> Advanced -> View White Space" if using Visual Studio to aid detection.
Expand Down