Comments 6
Облегчить навигацию по проекту
Обсудить файловую структуру: как грамотно разбить код на файлы.
Описать структуру каждого отдельного файла: где и что описывать.
Составить документацию со схемами классов.
Можно выбрать другую концепцию, например, для «приплюснутого» Си:
Всё есть классы.
Классы образуют иерархию.
Каждый класс это пара файлов, типа, *.h и *.cpp.
Составить диаграмму классов и общий алгоритм их взаимодействия, в рамках:
– Менеджера потоков;
– Менеджера событий;
– Менеджера видов (дочерних окон).
Определить требования к каждому объекту кода
Требования к переменным.
Требования к методам.
Место хранения этого всего.
Лучше, создать внутренний корпоративный документ по технологии программирования и формату оформления кода. Ну, и действовать в его рамках, в том числе, при создании документации.
А еще лучше, этот «документ по технологии программирования и формату оформления кода» опубликовать здесь, для обсуждения и усовершенствования. Но, лично я, предпочел бы обсуждать не технологию веб-программирования, а технологию взаимодействия графического интерфейса пользователя (GUI) с программной логикой приложения, для десктопных программ. Можно, с привлечением технологии вайбинга.
Если код не понятен - то стандарты и документация не сделает его более понятным, просто добавится непонятное описание для непонятного кода написанного по непонятным стандартам.
Вы это пробовали, или просто поверили на слово условному инфоцыгану "Саше"?
Почему интересуюсь?:
Изучал код межпоточной синхронизации в линуксе (где какой барьер памяти, кто кого "видит" до или видит после). И знаете, у меня сложилось странное впечатление:
Если изучать модели памяти и синхронизации ТОЛЬКО по коду, то понимание получается довольно слабым.
Если в дополнение к коду почитать и документацию с разбором пары примеров (в линуксе прикладывается файл с описанием и примерами) то становится НАМНОГО ПОНЯТНЕЕ!
Поэтому и интересуюсь, в каких случаях у Вас наличие стандартов и документации ухудшили понимание (с ваших слов: не сделали более понятным, но добавило непонятного)? Возможно есть отдельные области, где документация не нужна или даже вредна?
Справедливое уточнение.
Поверьте Саше - для проектов которые "в разработке", это так.
И добавьте документацию, если проект вышел в релиз и перешел в состояние "на поддержке". (Это отдельная от разработки задача - написать хорошую документацию человеческим языком)
Если у вас не открытый код, который будут изучать другие, то и этот шаг можно пропустить, по причине все тех же затрат.
Тут вопрос целесообразности. Саша подсветил, что во многих случаях - писать документацию не целесообразно. Тем более в наше время, когда всё это делает AI практически на лету.
Больше похоже на размышления gpt чем на личный опыт
Как упростить разработку: опыт и размышления (компиляция из моей переписки)