10 лучших советов по написанию читабельного кода
Тема легко читаемого кода знакома всем программистам. Хорошо отформатированный и написанный в соответствии стандартам код - предмет для гордости, им можно делиться с другими разработчиками, использовать снова и снова в новых проектах. В статье собраны наиболее важные и популярные практики.
Комментирование и документирование
Очень полезной фичей в Visual Studio является возможность комментариев в пользовательских классах и методах, в С# приложениях просто надо добавит три слеша ("///") перед их объявлением.VS.NET автоматически создает необходимые XML атрибуты, куда можно вставлять описание и информацию о параметрах. После того как проект скомпилирован, VS.NET сохраняет введенную информацию, и она будет отображаться с использованием IntelliSense. Эта информация включает комментарии для методов, параметры методов, возвращаемые переменные методов, перечислений и свойств.
Избегайте очевидных комментариев
Комментарии должны описывать цель секции кода, но не механизм как достичь эту цель - описывайте скорее "почему", а не "как". Если вы заметили, что комментариях используете имена переменных, лучше остановится и переписать комментарий.
Не правильно:
// получить код
countryCode = GetCountryCode(ServerType.BackUp);
// если код US
if (countryCode == "US")
// показать пользователя
InvokeUSUser();
Правильно:
// отобразить пользователей с US
countryCode = GetCountryCode(ServerType.BackUp);
if (countryCode == "US")
InvokeUSUser();
Единый стиль в отступах
Все знают что надо делат отступы в коде, чтобы повысить его читабельность о структурированность. Есть несколько стилей:
Стиль №1
void DoSomething() {
if (maybe) {
DoItNow();
Again();
} else {
AbortMission();
}
}
Стиль №2
void DoSomething()
{
if (maybe)
{
DoItNow();
Again();
}
else
{
AbortMission();
}
}
Выбор стиля зависит от вас, здесь самое лучшее правило - последовательность, если выбрали один, то придерживайтесь его всю жизнь :), ну или на протяжении одного проекта по крайней мере.
Еще по структуре отступов:
-
Разбивайте длинные SQL запросы на несколько строчек используя verbatim strings, т.е. использовать "@" в начале строки. Выравнивать последующие строчки лучше по началу SQL выражения в первой строчке . Тоже правило работает для вызова функций с большим количеством параметров
strSQL = @"SELECT tblAssemblyDetail.*, tblInventory.Description, tblInventory.Serials FROM tblInventory RIGHT JOIN tblAssemblyDetail ON tblInventory.ItemID = tblAssemblyDetail.ItemID WHERE ((tblAssemblyDetail.Assembly)='Package A') ORDER BY tblAssemblyDetail.LineNumber;" ; -
Разбивайте длинные объявления методов на несколько строчек и отступайте на 6 символов или 2 TAB отступа. Тоже правило работает для длинных IF выражений.
public void CreateNewNote( long accountNumber, string noteDate, string startTime, string note, long repNumber){} -
Когда присваиваете переменной длинное выражение, лучше сделать перенос сразу после знака "=", чтобы было видно все выражение в одной строчке.
grdDetail.Columns("CanBuild").Text = (long)lngQuantityLocation / (long)grdDetail.Columns("Needed").Text;
Группируйте код
Чаще всего определенные задания занимают несколько строк кода. Хорошая идея группировать эти задания в отдельные блоки, с разделителем - пустая строка.
// initialization
SqlDataAdapter adapter;
SqlConnection connection;
SqlCommand command;
// getTicketID
string sqlCommand = " SELECT * FROM Cases "
command = new SqlCommand();
Добавление строки комментариев перед каждым блоком также визуально подчеркивает разделение .
Избегайте глубоких вложений
Слишком много уровней вложенности усложняют читабельность кода и его тяжелее отследить. Часто можно внести некоторые изменения в код для большей читабельности.
Не правильно:
public int DoSmth(){
if (IsWritable(folder)) {
if (fp == FileOpen(filePath,"w")) {
if (stuff = getSomeStuff()) {
if (FileWrite(filePath,stuff)){
// ..
} else {
return false;
}
} else {
return false;
}
} else {
return false;
}
} else {
return false;
}
}
Правильно:
public int DoSmth(){
if (!IsWritable(folder))
{
return false;
}
if (fp != FileOpen(filePath, "w"))
{
return false;
}
if (stuff != getSomeStuff())
{
return false;
}
if (!FileWrite(filePath, stuff))
{
//..
}
else
return false;
}
Организация файлов и папок
Технически можно весь код содержать в одном файле, но его будет очень тяжело читать и поддерживать. Лучше всего разделять решение(Solution) на разные проекты (projects) в соответствии с разными уровнями, модулями, или компонентами определенными на стадии дизайна.
В платформе .NET вводиться понятие проекта, одно решение может включать несколько проектов разных типов. После того как вы начинаете все разделять на разные проекты их может стать слишком много, и становится неудобно скролить между ними.
В Visual Studio 2005 ввели полезную фичу: возможность добавлять папки в одно решение, группировать проекты и даже папки в вашей собственной логической иерархи.
Для примера пользуясь руководством Microsoft Patterns and Practicies по разработке трехуровневой архитектуры приложения, у вас может получиться что-то типа:
Будьте последовательны в именовании переменных
Как правило имена переменных имеют смысловую нагрузку и состоят из нескольких слов. Но это не обязательно так для локальных переменных. Они могут состоят и из одного символа. Хорошей практикой является использование единого принципа в именовании локальных переменных во всем проекте. Например:
// i для переменной счетчика циклов
for (int i = 0; i < 10; i++)
// j для вложеных циклов
for (int j = 0; j < 10; j++)
// ret для возвращаюшей результат переменной
public int Foo()
{
ret["bar"] = GetBarCode();
ret["stuff"] = GetStuff();
return ret;
}
// fp для указателя файла (file pointer)
fp = FOpen("file.txt","w");
Тут также стоит вспомнить про Венгерскую нотацию. Суть Венгерской нотации сводится к тому, что имена идентификаторов предваряются заранее оговорёнными префиксами, состоящими из одного или нескольких символов. Пример:
|
Class |
cls |
clsEmployee |
|
Form |
frm |
frmLogin |
Многие считают, что нотация устарела, но это хорошая практика быть последовательным и единым в именовании переменных.
Пишите SQL спец. слова заглавными буквами
Обращение к базам данных важная часть большинства WEB приложений. Если вы часто используете запросы, хорошая идея сделать их также более читабельными. Общепринятой практикой считается писать заглавными словами спец. слова SQL:
string statement = @"SELECT DISTINCT titel as linieName
FROM qry_Forecast_Taktzeiten
WHERE linieName LIKE 'lin%'; ";
DRY принцип
DRY расшифровывается как Don’t Repeat Yourself (Не повторяйтесь). Также известно выражение DIE: Duplication is Evil(Повторение - зло). Принцип гласит:
“ Каждый сегмент знаний должен иметь единственное и однозначное представление в рамках системы".
В ASP.NET можно использовать эталонные страницы( master pages) для задания шаблона всего сайта.
Если вам все таки надо использовать кусок кода снова и снова, то его можно перенести на панель инструментов(ToolBox), просто выделите ваш код и перетащите выбранный текст на общую вкладку. Теперь шаблон можно использовать как любой другой контрол.
Рефакторинг
Рефакторинг — процесс изменения внутренней структуры программы, не затрагивающий её внешнего поведения и имеющий целью облегчить понимание её работы. В основе рефакторинга лежит последовательность небольших эквивалентных (то есть сохраняющих поведение) преобразований. Лучше проводить рефакторинг недавно написанного кода, пока он свежий в голове, что бы потом легче было его читать и использовать. Хорошая книга по рефакторингу "31 Days of Refactoring"
Использованные материалы:
- Top 15+ Best Practices for Writing Super Readable Code
- "Visual Studio .NET Tips and Tricks". by Minh T. Nguyen.
Компании из статьи
| Microsoft Украина |  Украинское подразделение компании Microsoft. |