practical csharp
1.0.0
Коллекция в основном разумных руководящих принципов и лучших практик для написания чистого, читаемого, понятного и обслуживания C# кода.
var при необходимости и возможноЦель: лучшая читаемость и чистота
ХОРОШИЙ
var httpClient = new HttpClient ( ) ;ПЛОХОЙ
HttpClient httpClient = new HttpClient ( ) ; Цель: лучшая читаемость и чистота
ХОРОШИЙ
var user = new User
{
Username = "admin" ,
Age = 31
} ;ПЛОХОЙ
var user = new User ( ) ;
user . Username = "admin" ;
user . Age = 31 ; string.FormatЦель: лучшая читаемость и семантика
ХОРОШИЙ
var url = "http://localhost/api" ;
var resource = "users" ;
var path = $ " { url } / { resource } " ;ПЛОХОЙ
var url = "http://localhost/api" ;
var resource = "users" ;
var path = string . Format ( "{0}/{1}" , url , resource ) ;Цель: не нужно избегать персонажей BackSlash
ХОРОШИЙ
var path = @"C:UsersAdministratorDocuments" ;ПЛОХОЙ
var path = "C: \ Users \ Administrator \ Documents" ;Цель: рефакторирование может стать кошмаром, когда струнные литералы распределяются повсюду
ХОРОШИЙ
const string error = "user_not_found" ;
Log . Error ( error ) ;
return BadRequest ( error ) ;ПЛОХОЙ
Log . Error ( "user_not_found" ) ;
return BadRequest ( "user_not_found" ) ; xyz . Это просто смешно.Цель: укорочение имен переменных не добавляет никакого значения, он даже усложняет код более трудным для чтения и понимания
ХОРОШИЙ
// Nice
var validationResult = validator . Validate ( ) ;
// Nice
var stringBuilder = new StringBuilder ( ) ;
// Nice
const string directorySeparator = "/" ;ПЛОХОЙ
//
var res = validator . Validate ( ) ;
//
var sbd = new StringBuilder ( ) ;
// Seriously?
const string dsep = "/" ;Цель: облегчает код.
ХОРОШИЙ
// The purpose of this class can be easily inferred
public class OrderManager
{
// Using "Is" or "Has" as prefix clearly indicates that a method returns a boolean value
public bool IsFulfilled ( Order order )
{
}
public bool HasPositions ( Order order )
{
}
// Using a verb clearly indicates that a method performs some action
public void ProcessOrder ( Order order )
{
}
public void CancelOrder ( Order order )
{
}
}ПЛОХОЙ
// Purpose of this class can not be easily inferred
public class OrderHelper
{
// Unclear
public bool Fulfilled ( Order order )
{
}
// Unclear => users would likely expect a method that retrieves the positions of the order due to the verb "Get"
public bool GetPositions ( Order order )
{
}
// Unclear
public void Order ( Order order )
{
}
// Unclear
public void StopOrder ( Order order )
{
}
}Цель: делает код без необходимости дольше и труднее читать и понять
ХОРОШИЙ
// Clearly an interface
public interface IOrderManager { }
// Clearly a list of orders
private IList < Order > orders ;ПЛОХОЙ
// Clearly an interface => no "Interface" postfix necessary
public interface IOrderManagerInterface { }
// Clearly a list of oders => no "List" postfix necessary
private IList < Order > orderList ;Цель: Практика показывает, что комментарии могут быть устаревшими очень легко и быстро, когда база кода растет и развивается. Наличие самоэффективной базы кода способствует улучшению обслуживания и снижает необходимость писать и поддерживать ненужные комментарии. (Это не значит, что написание комментариев устарело.)
ХОРОШИЙ
public class OrderManager
{
public void ProcessOrder ( Order order )
{
var items = order . GetItems ( ) ;
foreach ( var item in items )
{
var availability = item . GetAvailability ( ) ;
}
}
}ПЛОХОЙ
public class OrderManager
{
public void ExecuteOrder ( Order order )
{
// Get all available items from the order
var data = order . GetData ( ) ;
foreach ( var x in data )
{
// Determine the availability of the item
var available = item . CheckAvailability ( ) ;
}
}
}Цель: в соответствии с структурой .NET и легче читать
ХОРОШИЙ
public class JsonParser { }ПЛОХОЙ
public class JSONParser { } Цель: enum всегда рассматривается индивидуально. Например EmploymentType.FullTime EmploymentTypes.FullTime . Кроме того, классы всегда представляют один экземпляр объекта, например, отдельного User . Исключение: битовое поле перечисления
ХОРОШИЙ
public enum EmploymentType
{
FullTime ,
PartTime
}
public class User
{
}ПЛОХОЙ
public enum EmploymentTypes
{
FullTime ,
PartTime
}
public class Users
{
} Цель: синтаксический сахар ¯ (ツ) /¯
ХОРОШИЙ
public class User
{
public string Username { get ; }
public int Age { get ; }
public string DisplayName => $ " { Username } ( { Age } )" ;
public User ( string username , int age )
{
Username = username ;
Age = age ;
}
}ПЛОХОЙ
public class User
{
public string Username { get ; }
public int Age { get ; }
public string DisplayName
{
get
{
return $ " { Username } ( { Age } )" ;
}
}
public User ( string username , int age )
{
Username = username ;
Age = age ;
}
} Цель: Лучше осознание того, что пошло не так. Позволяет больше точности во время журнала и анализа ошибок.
ХОРОШИЙ
try
{
System . IO . File . Open ( path ) ;
}
catch ( FileNotFoundException ex )
{
// Specific
}
catch ( IOException ex )
{
// Specific
}
catch ( Exception ex )
{
// Default
}ПЛОХОЙ
try
{
System . IO . File . Open ( path ) ;
}
catch ( Exception ex )
{
// SOMETHING went wrong
}Exception самостоятельно Цель: очень плохая практика. Exception s должны быть брошены только .NET Framework.
ХОРОШИЙ
public void ProcessOrder ( Order order )
{
if ( order == null )
{
throw new ArgumentNullException ( nameof ( order ) ) ;
}
}ПЛОХОЙ
public void ProcessOrder ( Order order )
{
if ( order == null )
{
throw new Exception ( "Order is null." ) ;
}
} Цель: лучшая читаемость
ХОРОШИЙ
private string _username ;ПЛОХОЙ
private string mUsername__ ;
// OR
private string username ;
// OR
private string username_ ; Цель: лучшая читаемость, экономит пространство
ХОРОШИЙ
public class JsonParser
{
private readonly string _json ;
public JsonParser ( string json )
{
_json = json ;
}
}ПЛОХОЙ
public class JsonParser
{
private readonly string _json ;
public JsonParser ( string json )
{
_json = json ;
}
} Цель: предотвращает случайное изменение имущества с других мест, лучшего прогнозирования поведения приложения
ХОРОШИЙ
public class JsonParser
{
public string Json { get ; }
public JsonParser ( string json )
{
Json = json ;
}
}ПЛОХОЙ
public class JsonParser
{
public string Json { get ; set ; }
public JsonParser ( string json )
{
Json = json ;
}
}Цель: предотвращает изменение коллекции с в других местах, лучшего прогнозирования поведения приложения
ХОРОШИЙ
public class KeywordProvider
{
public IReadOnlyCollection < string > Keywords { get ; }
public KeywordProvider ( )
{
Keywords = new ReadOnlyCollection < string > ( new List < string >
{
"public" ,
"string"
} ) ;
}
}ПЛОХОЙ
public class KeywordProvider
{
public IList < string > Keywords { get ; }
public KeywordProvider ( )
{
Keywords = new List < string >
{
"public" ,
"string"
} ;
}
} using блоков Цель: Ресурс автоматически утилизируется при using блока
ХОРОШИЙ
using ( var connection = new SqlConnection ( connectionString ) )
{
}ПЛОХОЙ
try
{
var connection = new SqlConnection ( connectionString ) ;
}
finally
{
connection . Close ( ) ;
connection . Dispose ( ) ;
} Цель: лучшая читаемость, легкое обслуживание, когда в условиях требуется другая линия
ХОРОШИЙ
if ( user . IsElevated )
{
// Do something
}ПЛОХОЙ
if ( user . IsElevated )
// Do somethingЦель: чтобы вы знали, какая часть сообщения содержит переменные.
ХОРОШИЙ
var filePath = @"C:tmpmy-file.txt" ;
try
{
var file = File . Open ( filePath ) ;
}
catch ( Exception ex )
{
// GOOD: Add [ ] to the variable
Log . Error ( $ "Could not open file [ { filePath } ]." , ex ) ;
}ПЛОХОЙ
var filePath = @"C:tmpmy-file.txt" ;
try
{
var file = File . Open ( filePath ) ;
}
catch ( Exception ex )
{
Log . Error ( $ "Could not open file { filePath } ." , ex ) ;
}Цель: чтобы исключение можно было отфильтровать в определенных случаях (например, в пользовательском интерфейсе, поскольку вся трассировка стека бесполезна для пользователя).
ХОРОШИЙ
try
{
var file = File . Open ( @"C:tmpmy-file.txt" ) ;
}
catch ( Exception ex )
{
// Use appropriate signature of your logger to include the exception as separate parameter
Log . Error ( "Could not open file." , ex ) ;
}ПЛОХОЙ
try
{
var file = File . Open ( @"C:tmpmy-file.txt" ) ;
}
catch ( Exception ex )
{
// Strictly AVOID this. The exception is added directly to the log message, which makes it impossible to filter the exception
Log . Error ( $ "Could not open file: { ex } " ) ;
}
