Как держать в голове проект по программированию над которым работаешь не каждый день?

Question

[Dum_spiro_spero]

Добрый день, ситуация следующая...
Несколько месяцев работаю над неким проектом. Программирую штуку связанную с численными методами решения диффуров и физикой. Когда начинал - все было просто и легко удерживалось в голове. Далее проект стал разрастаться - из за того, что в самом начале не представлял всех сложностей с которыми столкнусь. Над проектом работаю не каждый день, и обнаружилась следующая проблема - если не позаниматься проектом несколько дней - то потом трудно вспомнить на чем я остановился, зачем введены те или или иные куски кода. Пишу комментарии - но не хватает, ощущение, что надо писать развернутые письма самому себе (почти как в фильме "Memento"). В результате день уходит на то, чтобы разобраться что же я делал неделю назад - а на следующий день можно уже писать нормально.
Я не программист, а физик, поэтому могу не знать каких-то типичных и очевидных методов решение таких организационных вопросов. Посоветуйте как быть!

Answer 1

[Алексей Яхненко]

1. Писать самодокументирующийся код.
2. Щедро добавлять стандартизированные комментарии к каждой функции и переменной.
3. Рефакторить структуру до полной очевидности.
4. Использовать git с подробными описаниями коммитов - с помощью аннотаций будет легко понять зачем написан тот или иной кусок
5. Вести TODO отдельно либо используя @todo комментарии прямо в коде.

Comments

[Dum_spiro_spero]

"самодокументирующийся код" - а что это? В смысле это термин или некий признак кода?

[Алексей Яхненко]

Вкратце - код, в котором переменные и функции названы так, что их можно читать как текст.
Скорее набор практик что ли.

[Mrrl]

С пунктом 2 есть большая проблема. Допустим, в проект пришлось внести небольшое изменение - поменялся смысл одного из параметров, несколько параметров объединились в структуру, добавились новые... Поменять придётся 10-15 функций, образующих небольшое дерево. При этом в результате изменений комментарии, естественно, устареют.
И что делать? Пока мы меняем код, списки сделанных и необходимых изменений удержать в голове можно (если никто не отвлекает). Если после каждого изменения функции исправлять её комментарий, то точно забудем, что и как теперь надо менять. Если же комментарии не менять, то после того, как избавимся от ошибок компиляции, всё отладим и протестируем - забудем, какие функции менялись, и какие комментарии теперь надо исправлять.
Кстати, пока будем изобретать новое имя переменной для самодокументированного кода - то тоже половина необходимых изменений вылетит из головы. На одновременное решение нескольких сложных задач мозг, всё-таки, не очень рассчитан.

[Алексей Яхненко]

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

"изобретать" имя переменной не надо - через некоторое оно само становится очевидно.

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

[Mrrl]

Алексей Яхненко: Даже если функции маленькие и решают одну задачу. Вот поменялась сигнатура у какого-то метода. Всё равно придётся пройтись по всем точкам его вызова, понять, как там получить необходимые для вызова данные. Возможно, придётся поменять и сигнатуру вызывающего метода, или изменить его логику...
У функции, которая вычисляет силу тока, могут, например, на входе добавиться единицы измерения - омы или килоомы. Может потребоваться узнать погрешность вычисления, тогда во всей программе придётся либо вводить в пару к измерению его погрешность, либо все числа заменять на структуры "число с погрешностью". Может потребоваться учесть температуру проводника, которая берётся из внешней модели (а раньше она в проекте не фигурировала вообще - температурные зависимости решили добавить только что).
Имя переменной может не успеть стать очевидным - за 5 минут написали функцию с однобуквенными переменными и пошли писать следующие функции, чтобы не забыть, что они должны делать. А потом, когда через месяц вернёмся к этой функции, придётся учиться читать код. Конечно, тогда и можно будет изобрести правильные имена, но придётся поработать.

[Алексей Яхненко]

сдаюсь )

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

создавая функцию с однобуквенными переменными вы как раз себе и создаете проблемы с пониманием этого кода через определенное время.

код пишется для человека а не для машины.
если знаете за собой, что забываете всякое - помогите себе, напишите комментариев.

[Mrrl]

Алексей Яхненко: Это не цейтнот. Это большой граф взаимосвязей, который лежит в голове и который надо выплеснуть в виде кода. И при этом не расплескать. Написание комментариев ухудшит дело так же, как и придумывание имён.
Хорошо, если я смогу угадать, на какие функции распадётся код. Тогда можно будет написать хотя бы их имена (а если повезёт - то и сигнатуры), и дальше использовать их в качестве скелета. Но при таком подходе начиная где-то с середины оказывается, что всё не так, и в таком порядке написать обработку за разумное время не удаётся. Приходится половину скелета ломать и начинать сначала...

[Dum_spiro_spero]

Mrrl: Аоуа! Вот-вот! Как хорошо вы структурировали проблему!!!

[Алексей Яхненко]

звучит так, будто вы программируете в состоянии напряжения.
найдите источник этого напряжения.

если вы не успеваете записывать свой код - вероятно вы не в полной мере используете возможности современных IDE.

[Dum_spiro_spero]

Алексей Яхненко:
"звучит так, будто вы программируете в состоянии напряжения.
найдите источник этого напряжения." О, да! Та прога надстройку к которой я пишу переписана на С++ индусами много лет назад. И она э... крайне дураконеустйочива. Неправильный шаг - и будьте добры закрыть программу, загрузить файл целиком, и т.п... ну и сам не на 100% знаю эту систему - так что постоянное непонимание, то ли я дурак, то ли индусы (как правило все же я).
"вероятно вы не в полной мере используете возможности современных IDE."
Это 100% так. Но увы - нет возможности из использовать.

[Алексей Яхненко]

Dum_spiro_spero: тогда я просто пожелаю вам удачи и хорошей кармы )

[Dum_spiro_spero]

Алексей Яхненко: Спасибо!

Answer 2

[xmoonlight]

То же самое что и zoom на карте:
1. делаете общую схему с функциональными блоками и их связями. блоки - нумеруются.
2. каждый блок - детализируете в новой схеме.
* тут делаете текстовые описание связей и все, что относится к схеме/к процессу в отдельном docx/xlsx-документе. (google docs)
* на основе этого - не составит труда описать функции для кодинга, если позволяет уровень детализации данной схемы.
3. goto 2.

(разумно использовать draw.io и подключить к google docs/google disk)

Answer 3

[asd111]

Желательно использовать ООП.
При использовании ООП можно сначала нарисовать схемы - так называемые диаграммы UML — в них обычно написано что какой класс делает и нарисовано как он связан с другими.

Сначала рисуете диаграммки что с чем как связано и потом пишете код.

Выглядит примерно так:

pvti.ru/data/image/pages/webkurs/p3_9.gif

На данных диаграммах в первой строчке - название класса, во втором блоке - названия переменных, в третьем блоке - названия методов(функций). Стрелочки показывают как классы взаимодейтсвуют между собой, кто от кого наследуется и кто какие методы вызывает и т.д.

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

Comments

[Dum_spiro_spero]

Спасибо! ++ я, увы - не могу использовать. У меня всё из функций и в лучшем случае структур.

Answer 4

[Денис Инешин]

Нарисовать схему.
+ вести TODO со списком уже сделанных и планируемых задач.

Comments

[Dum_spiro_spero]

Сложность в чем - вроде кусок сделан - но не работает как надо. А почему? Опечатка, ошибка в алгоритме, ошибка в другом блоке...
Если есть какая-нибудь литература - типа "как писать одному большие программы" - посоветуйте, плиз.

[Денис Инешин]

Dum_spiro_spero: о, вот вы о чем. А вот тут вам нужно освоить тесты, это помогает в сложных программах, делая новые фичи, не ломать остальное.

[Mrrl]

Схему чего? Проект ещё не готов, и каким он будет в готовом варианте - совершенно неизвестно.

[Денис Инешин]

Mrrl: схему того, что сделано.

Answer 5

[Unknown Hero]

Если пишите тесты, то перед окончанием работы создавайте нерабочий тест.
Когда сядите заново, запускаете тесты и вспоминаете , что хотели сделать в последнйи раз.

Answer 6

[Макс Сысоев]

Есть поверье - если коду требуется комментарий, его нужно вынести в функцию с говорящим за себя именем

Answer 7

[argumentum]

Кажется, автору вопроса надо внимательно проработать книги:
1) Стив Макконнелл - "Совершенный код"
2) Мартин Фаулер и др. - "Рефакторинг. Улучшение существующего кода."

А по поводу "потом трудно вспомнить на чем я остановился, зачем введены те или или иные куски кода" - помогут системы управления версиями при условии комментирования изменений.

Comments

[Dum_spiro_spero]

Спасибо за названия. Надо прочитать.
"системы управления версиями"
Про это тоже слышал ))) Надо внедрять. Порекомендуйте что именно и где почитать.

[argumentum]

Dum_spiro_spero: Дело в том, что если упомянутые книги я перечитал даже не раз, и во многом они изменили мой подход к кодированию, то системами управления версий я вего лишь немного побаловался лет 10 назад и пока их не применяю. Это из-за того, что программирую немного и небольшие ... их даже проектами назвать сложно, эдакие микропроектики. Там запутаться сложно.

А системы управления версиями действительно необходимы, когда проекты большие и/или их много и/или код запутанный.

Данных систем есть несколько разных, народ вроде бы сходится во мнении, что попроще и для малых проектов - svn (Subversion), для больших проектов и понавороченнее - например, git.

Обсуждение, что лучше выбрать начинающему:
ru.stackoverflow.com/questions/159736/%D0%9A%D0%B0...

Книга по Subversion:
kharchuk.ru/svn.html

Мануалы по git для начинающих:
githowto.com/ru
jakeroid.com/osnovy-sistemy-upravleniya-versiyami-...
htmlstudio.ru/git-%D0%B4%D0%BB%D1%8F-%D0%BD%D0%B0%...

[Dum_spiro_spero]

argumentum: Спасибо! Открыл - читаю.

Answer 8

[Ilya Bobkov]

В голове не удержать, а напоминать себе как-то надо.

Answer 9

[Mrrl]

Можно просто периодически читать/просматривать код, вспоминая, что к чему, как оно выглядит, откуда вызывается и кого вызывает, в каких ситуациях работает та или иная часть кода... Чтобы ориентироваться на местности, надо по ней иногда гулять, и не бояться заблудиться :)

Answer 10

[Dum_spiro_spero]

Попробую резюмировать.
1. Надо изначально хорошо продумать и расписать/разрисовать структуру проекта.
-увы - иногда она начинает меняться по ходу пьесы - значит плохо продумали.
2. Разбивать программу на мелкие блоки.
3. Комментировать все что можно и нельзя.
4. Видимо писать письма самому себе и художественные размышления зачем здесь то или иное.
Большое спасибо всем за ответы!
Кстати - я один такой - страдающий программистким склерозом или это распространено?

Comments

[therhino]

1. Не обязательно плохо продумали, банально что-то может поменяться
2. Вообще, ИМХО, комментарии считаю злом. Если есть необходимость в комментариях, значит нужно менять код
Да все люди одинаковые. Иногда кажется что что-то у тебя одного как-то "не так", а это у множества других людей.

[Dum_spiro_spero]

therhino: Ого! А какие задачи вы программируете?

[Алексей Немиро]

therhino: комментировать нужно, чтобы уменьшить время на вхождение в проект или отдельные области кода, особенно при командной работе, особенно в больших проектах.

Dum_spiro_spero: хорошо продумывать необязательно, можно делать и менять в процессе. Как ни странно, но изначально хорошо продуманные проекты нередко остаются просто хорошо продуманными проектами, без реализации или же с никому не нужной реализацией. Даже если все продумано и сделано идеально, со временем будет бардак. Миром правит хаос :)

Измельчать следует аккуратно, если переусердствовать, проект может получится излишне сложным. Нечто вроде лабиринта, путешествие по которому не будет доставлять никакого удовольствия и будет съедать много времени.

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

В молодости, еще помню, была память хорошая, все держалось в голове и даже комментарии можно было не писать. Но старею, проектов становится больше и они существенно крупнее и сложнее. Дело доходит до того, что каждый понедельник приходится вспоминать, над чем я работал в пятницу. Быстро вспоминать помогает использование единых правил разработки, заметки в комментариях, если я что-то не доделал или запланировал на будущее, ну и задания самому себе :-) В заданиях, если использовать систему управления проектами, что-нибудь на подобии Assembla, ссылку на которую я показал в своем ответе, можно описывать ход выполнения задачи. Например обычно, когда я отправляю изменения кода в систему контроля версий, то указываю комментарий к заданию, к которому относятся изменения. Потом можно просто открыть задание и посмотреть ход его выполнения. Главное не забыть название и расположение проекта, над которым работаешь :-))