Когда вы начинали свой путь программирования, вы, вероятно, писали код только для того, чтобы попрактиковаться в приобретенном наборе навыков или для своего небольшого личного проекта. Вы пишете код, он работает, и вы о нем забываете. Когда вы смотрите на этот кусок кода через несколько месяцев, вы его не понимаете. 😕 По мере того, как наше путешествие по программированию продолжается, мы начинаем понимать, что программирование — это не только технические навыки, но и в равной степени взаимодействие между командами.

Вот почему важно, чтобы вы писали код, понятный другим программистам. Будь то экспертная оценка или просто понимание устаревшей системы, программисты всегда будут посещать ваш код. И как программист, вы также несете ответственность за поддержку своего кода. В этой статье мы обсудим пять важных советов, которые определенно облегчат эту часть процесса. Пойдем. 🏃

[1] Правильно называйте все

Имена повсюду в нашем исходном коде, будь то функция, класс, аргумент, переменные, имена файлов , а что нет. На самом деле именно имена делают код понятным для программиста. Поэтому написание хороших имен должно стать вашим первым шагом в поддержании понятной кодовой базы.

  • Используйте для всего простые, понятные, осмысленные и раскрывающие намерения названия. Это означает вашу переменную, ваши методы, ваши классы и ваши имена файлов. Если имя вашей переменной или метода не помогает понять, по крайней мере, что делает метод или класс, вы можете переименовать их.
// what difference is this method calculating?
// diffrence in minutes?
// difference in days?
//difference in milliseconds?
function getDifference(DateTime dt1, DateTime dt2) { ... }

//a better solution ??
function diffInDays(DateTime dt1, DateTime dt2) { ... }
  • Используйте имена, доступные для поиска и произносимые для других программистов, потому что это значительно упрощает общение в вашей команде. Было бы обидно, если бы для каждого нового программиста, присоединившегося к вашей команде, вам пришлось бы тратить некоторое время на простое описание того, что означают переменные.
// which names would you prefer ??
int vId;
int videoId; 

double vidMs;
double videoDurationInMilliseconds;
  • Используйте согласованный шаблон именования. Значение Не используйте разные слова для описания одного и того же контекста. Не пишите три разных имени класса, например AdminManager, StudentController и EmployeeProcessor, для одной и той же концепции. Не называйте свои методы тремя разными способами, например: getAdmin(), fetchStudent() и retreiveEmployee(), потому что это очень сбивает с толку тех, кто пытается понять ваш код.
  • Используйте имена доменов решений, потому что использование связанных с программированием терминов, таких как имена алгоритмов, имена шаблонов проектирования и математические термины, полезно для других программистов. Так что просто назовите свой класс StudentFacadeесли это фасад, вместо того, чтобы называть его как-то иначе.

[2] Правильно комментируйте исходный код

После имен комментарии — это то, что делает код читабельным. Так что продолжайте и комментируйте свой исходный код, когда это необходимо. НО ПОМНИТЕ !! Комментарии не должны исправлять плохой код.

  • Пишите информативные комментарии, которые еще больше выражают цель вашего кода.
//matches the yyyy-MM-dd format
String dateTimeRegex = ((?:19|20)\\d\\d)-(0?[1-9]|1[012])-([12][0-9]|3[01]|0?[1-9]);
  • При необходимости используйте комментарии, которые могут немного пояснить код.
assertTrue(a.compareTo(a) == 0); //a == a
assertTrue(a.compareTo(b) != 0); //a != b
assertTrue(a.compareTo(b) == -1); // a < b
assertTrue(bb.compareTo(ba) == 1); //bb > ba
  • Предоставьте ссылку на такие веб-сайты, как stackoverflow, laracasts, если внешняя ссылка обеспечивает большую ясность для кода, который вы предоставляете.
/**
* ref : https://stackoverflow.com/questions/475074/regex-to-parse-or-validate-base64-data
**/  
function validBase64Image(base64Image: string): boolean 
{
    const regex = /^data:image\/(?:gif|png|jpeg|bmp|webp|svg\+xml)(?:;charset=utf-8)?;base64,(?:[A-Za-z0-9]|[+/])+={0,2}/;
    return base64Image && regex.test(base64Image);
}

[3] Сделайте отступ в коде для лучшей читабельности

Да !! Отступы — часто упускаемая из виду часть удобства чтения кода. Код с правильным отступом намного легче просматривать, чем код с плохим отступом.

Подробнее об этом читайте в этой замечательной статье, которую я нашел.

https://firstclassthoughts.co.uk/Articles/Readability/OptimalIndentSizeForCodeReadability.html

[4] Говорите кратко и просто

Возможно, вы сталкивались с различными принципами программирования, такими как: Будь проще, глупее (KISS), Не повторяйся (DRY), Принцип единой ответственности (SRP) и так далее. Что общего у всех принципов, так это то, что вы делаете свои методы, классы короткими и простыми.

Ни один программист не захочет изучать ваш метод из 200 строк кода, чтобы понять, как он работает. Он/она просто сдастся. С другой стороны, обход методов с 5–10 строками кода кажется относительно простым.

[5] Использование тестов в качестве документации

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

Даже лучше, чем документация? Да, если вы позволите своим тестам. Видите ли, тесты никогда не устаревают, потому что они всегда будут проверять последнее поведение, ожидаемое от кода. Сравните это с фактической документацией, которую разработчики могут забыть обновить, поэтому она будет устаревшей. На самом деле тесты являются основным источником правды, и они также могут быть в состоянии проверить правильность документации.

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

Заключение

Читаемая и понятная система одинаково важна наряду с системой, которая работает. Программирование — это понимание системных требований, преобразование требований в код и изменение кода по мере изменения требований системы. Поскольку программирование — это командная работа, вы будете постоянно проверять код своих коллег-программистов, а ваш код будет проверять кто-то другой. Вы будете много общаться, говоря о коде, коде и коде! Вот почему важно, чтобы вы также поддерживали свой код.