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

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

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

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

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

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

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

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

сдаюсь )

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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%...

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

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

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

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

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

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

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

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