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


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


Ще за структурою відступів:




  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 з розробки трирівневої архітектури додатку, у вас може вийти щось типу:



Рефакторинг


Рефакторинг – процес зміни внутрішньої структури програми, що не зачіпає її зовнішньої поведінки і має на меті полегшити розуміння її роботи. В основі рефакторінгу лежить послідовність невеликих еквівалентних (тобто зберігають поведінка) перетворень. Краще проводити рефакторінг недавно написаного коду, поки він свіжий в голові, що б потім легше було його читати і використовувати. Хороша книга по рефакторінгу тут.

Схожі статті:


Сподобалася стаття? Ви можете залишити відгук або підписатися на RSS , щоб автоматично отримувати інформацію про нові статтях.

Коментарів поки що немає.

Ваш отзыв

Поділ на параграфи відбувається автоматично, адреса електронної пошти ніколи не буде опублікований, допустимий HTML: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

*

*