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();

        void DoSomething() { 

            if (maybe) { 
                DoItNow();
                Again(); 
            } else {
                AbortMission();
            }
        }

        void DoSomething()
        { 

            if (maybe) 
            { 
                DoItNow();
                Again(); 
            }
            else 
            {
                AbortMission();
            }
        }

Выбор стиля зависит от вас, здесь самое лучшее правило - последовательность, если выбрали один, то придерживайтесь его всю жизнь :), ну или на протяжении одного проекта по крайней мере.

Еще по структуре отступов: 

1. Разбивайте длинные 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;" ;
   

2. Разбивайте длинные объявления методов на несколько строчек и отступайте на 6 символов или 2 TAB отступа. Тоже правило работает для длинных IF выражений.

         public void CreateNewNote( long accountNumber,
                             string noteDate, string startTime,      
                             string note, long repNumber){}  
   

3. Когда присваиваете переменной длинное выражение, лучше сделать перенос сразу после знака "=", чтобы было видно все выражение в одной строчке.

         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");  

Тут также стоит вспомнить про Венгерскую нотацию. Суть Венгерской нотации сводится к тому, что имена идентификаторов предваряются заранее оговорёнными префиксами, состоящими из одного или нескольких символов. Пример:

Многие считают, что нотация устарела, но это хорошая практика быть последовательным и единым в именовании переменных. 

Пишите 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), просто  выделите ваш код и перетащите выбранный текст на общую вкладку. Теперь шаблон можно использовать как любой другой контрол. 

Рефакторинг

Рефакторинг - процесс изменения внутренней структуры программы, не затрагивающий её внешнего поведения и имеющий целью облегчить понимание её работы. В основе рефакторинга лежит последовательность небольших эквивалентных (то есть сохраняющих поведение) преобразований.  Лучше проводить рефакторинг недавно написанного кода, пока он свежий в голове, что бы потом легче было его читать и использовать. Хорошая книга по рефакторингу тут.

Ссылки по теме

• Купить продукты Microsoft в интернет-магазине ITShop.ru
• Купить Visual Studio 2008 в интернет-магазине ITShop.ru
• Курсы обучения компании Microsoft в интернет-магазине ITSHhop.ru
• Подписаться на рассылку "Мастерская программиста"