Техническая документация позволяет оценить стоимость разработки и согласовать функциональность будущей системы. При возникновении споров о стоимости и сроках разработки той или иной фичи она может стать определенной гарантией для заказчика. С другой стороны, если возникнет потребность в развитии приложения, документация облегчит процесс доработки и даст четкое понимание, возможно ли встроить новую функциональность в существующую систему.
Другой пример — государственные организации или организации, чья деятельность ограничивается или подчиняется законам и надзорным органам. Они обязаны осуществлять разработку ПО по всем правилам и с соблюдением всех стандартов. В таких проектах техническая документация, подготовленная по ГОСТам, — необходимое условие.
И разумеется, грамотно составленная и актуальная документация необходима для того, чтобы каждый участник в процессе разработки мог обращаться к документам, если возникают вопросы по конкретной задаче или по всей системе в целом.
Техническое задание и технический проект — два разных документа. Техническое задание отвечает на вопрос «что нужно сделать?», его составляет аналитик в самом начале проекта. Технический проект разрабатывает технический писатель. Этот документ создается после ТЗ и отвечает на вопрос «как нужно делать?».
Объяснение:
Что новички делают не так
Неправильно выставляют отступы — их код просто не работает.
Используют неодинаковое количество отступов: в одной функции — два пробела, в другой — все шесть.
Используют разные клавиши, чтобы создать отступ: в одной функции — клавишу табуляции, в другой — два пробела.
Из-за разных отступов код смотрится некрасиво, а Python ругает за неудачное сочетание пробелов и табуляций.
Решение
Хороший тон — делать отступ четырьмя нажатиями пробела.
Современные среды разработки — например, PyCharm — упрощают жизнь программиста. Нажав клавишу табуляции, автоматически получаете четыре пробела. Вуаля: код оформлен в общепризнанном стиле.
Для языка Python разработан официальный документ PEP-8, в котором прописаны правила красивого кода. Это соглашение всех программистов мира, которые пишут на Python, о том, какой код считать образцовым.
Переменные: непонятные
Рабочий код должен быть читаемым и ясным без личного присутствия автора. Потрудитесь дать понятные имена всем переменным, методам, функциям, которые используете в коде.
Что новички делают не так
Используют в качестве переменных обычные буквы алфавита: a, b, c, d, — не задумываясь о смысловой нагрузке.
Называют все переменные любимой буквой, добавляя цифры: а1, а2, а3. Если переменных двадцать, то будет и а20. Понять, какую информацию они хранят, очень сложно.
Используют строчную переменную l. Разработчики стараются избегать эту букву. Ее не принято использовать не только в Python, но и в других языках программирования, потому что при быстром чтении кода строчную l легко спутать с единицей. Аналогичная путаница возникает с O и 0.
Записывают переменные транслитом (massiv вместо array).
Придумывают новые переменные для общепринятых: для названия цикла (в цикле используют переменные i, j, k — именно в таком порядке, от внешнего i до вложенного k), для обозначения осей координат (x, y).
Решение
Очередное правило хорошего кода: каждая переменная должна говорить о том, что она хранит. Для записи информации о человеке логично создать переменную name. Для возраста — age. Заглядывайте в онлайн-словари, чтобы называть переменные правильными английскими словами, понятными большинству программистов в мире. Идеальная переменная понятна и легко читается:
Если название переменной состоит из нескольких слов, используйте в Python нижнее подчеркивание: переменная со значением максимального размера — max_size.
Если именуете класс, записывайте каждое слово с заглавной буквы: имя_переменной должно отличаться от ИмениКласса.
Особенность языка Python в том, что он интерпретируемый. Программа не отслеживает, какие имена дает программист переменным, и примет любое имя, даже название функции.
Из этого вытекает еще одна ошибка новичков: они называют переменные так же, как функции.
В Python есть около 70 функций «из коробки»: функция sum() вычисляет сумму всех переданных аргументов, max() ищет максимальное значение. Если программист назовет переменную sum, она будет работать. Но такой переменной он переопределит функцию суммирования — и она сломается.
Пустые строки: отсутствуют или в избытке
Как правило, код джуниора идет сплошным текстом: в каждой строке — очередная строка кода.
Что новички делают не так
Не разделяют строки кода пустыми строками.
Отделяют каждую строчку кода пустой строкой.
В обоих случаях код очень сложно прочитать.
Решение
Код принято делить на логические блоки.
К примеру, если запрашивают информацию о пользователе, пишут несколько строк кода и оставляют одну пустую после блока.
Далее идет блок обработки информации. Если он содержит несколько подблоков, их тоже следует отделить пустой строкой.
Перед выводом информации в конце также добавляют пустую строку.
Слишком сжатый код
Что новички делают не так
Пытаются написать код максимально сжато и для этого помещают несколько составных операций в одну строку.
Такой код сложно отлаживать в больших проектах: его трудно читать, приходится разбираться в том, как он работает.
Решение
Если есть возможность, распишите несколько составных действий в отдельные строки. Лучше потратить две минуты сейчас и сэкономить двадцать минут на чтение этого кода в будущем.
Советы декана начинающим разработчикам
Ваш код будут читать другие программисты. Всегда думайте о том, как они его воспримут, насколько он будет понятен коллегам.
Потратьте время на изучение синтаксиса, почитайте стандарты PEP8. Есть англоязычная версия и перевод. Работодатель будет встречать «по одежке»: ваш код должен выглядеть красиво.
Если Python — не первый для вас язык программирования, повторяйте требования стиля. Когда разработчик пишет, не соблюдая их, возникает путаница: то ли перед нами человек, у которого в голове перемешались все языки программирования, то ли новичок, который вообще ничего не знает о Python.
Воспользуйтесь командой import this. Это пасхалка от разработчиков: она выводит свод правил хорошего кода. Почаще перечитывайте этот Дзен Python — и ваш код будет идеален.
var i, a, b, sum :integer;
begin
readln(a,b); sum:= 0; for i:= a to b do sum:= sum + sqr(i); writeln(sum);
end.
program task2;
var i, a, b, p :integer;
begin
readln(a,b); p:= 1; for i:= a to b do if (i mod 3 = 0) and (i mod 4 <> 0) then p:= p * i; writeln(p);
end.
program task3;
var i, exercise, sum :integer;
begin
for i:= 1 to 13 do begin readln(exercise); sum:= sum + 5 + exercise; if i = 5 then writeln(sum); if i = 10 then writeln(sum); end; writeln(sum);
end.