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

Replies (28)

  • @openminded, А что за код?
  • @Peter, Библиотека на c#. Для конструирования искусственного мира.
  • @openminded, Тогда да, тогда сам Балмер велел.
  • @Peter, Это в каком смысле? Я вообще про то, что мне проще сначала не тесты писать, а русским языком перечислить все, что мне нужно сделать. Практически интегрированное ToDo.
  • @openminded, По мне, так это похоже на отложенное проектирование.
  • @Peter, Наверное так и есть. На этапе проектирования у меня определились только интерфейсы. Вся реализация рождается в процессе.
  • @openminded, Подход хорош для случаев, когда проектирование сравнимо по времени с программированием. А если еще использовать Doxygen, можно получить документацию на выходе.
  • @Peter, Ну так она и так получается на выходе в виде XML. Разве что распарсить нужно. Doxygen кроме этого умеет что-нибудь вкусное?
  • @Peter, Спасибо
  • @Peter, Я вот думаю, как это написать документацию, чтобы ее один раз можно было прочитать и все было понятно. А то обычно же с одного раздела в другой приходится скакать и в итоге суть таки ускользает. Единственное, что мне приходит пока на ум — это описать сначала кратко, как все компоненты вместе работают, потом каждый по отдельности рассмотреть подробне, а потом снова рассмотреть всех попорядку, но уже на уровне реализации и API. Не слишком ли это?
  • @openminded, Велосипед по сути.
    1. Теоритеческое описание решаемой задачи (без упоминания о программе)
    2. UML-диаграммы классов.
    3. UML-диаграммы последовательностей.
  • @Peter, А в какое место вставить байки "как это было вначале" и "почему я тут сделал именно так"? В примечания UML?
  • @openminded, Документация должна быть краткой, чтобы ее хоть кто-то начал читать. Обоснование выбора архитектуры можно изложить в приложении, а можно вообще не писать.
  • @Peter, Логично, чего уж там. Просто я, как и многие, аудиал и plain text на меня действует лучше, чем диаграммы. Наверное буду делать оба варианта.
  • @openminded, Для plain text существует CRC-карты
  • @Peter, Да, но там все к интерфейсам подвязано. Нужно же еще объяснить, прототипом чего из реального мира является какой-то класс (я ведь не абстрактную программу делаю, а моделирующую мир), какие именно особенности своего прототипа он реализует. Чтобы потом можно было интерполировать свои знания о принципах работы реального мира на работу модели. У меня есть такая теория, что наилучший способ обучения — это вникнуть в суть, понять идеи и правила, которые лежали в основе. Тогда все остальное будет просто очевидно и логично вытикать из основ. Это как настроиться на определенный образ мышления.
  • @openminded, Если что, никто не станет менять образ мышления ради чтения документации. Что описывает какой класс должно быть понятно из его названия. Уровень абстракции модели описывается в первом пункте (Теоритическая часть).
  • @Peter, Значит это работает только для меня.
  • @openminded, Меня пол года назад жоско отодрали по теме документации, так что эти правила кровью писаны, кровью из моего ануса.
  • @Peter, А пока отдирали, ничего про документацию пользователя не говорили?
  • @openminded, документация пользователя? Не понял. Видимо нет...
  • @Peter, Ну как же? Документация разработчика — это те самые диаграммы классов и всякие апи-шмапи. В общем внутренности. А документация пользователя — это описание того, что и как нужно делать с готовым продуктом, у которого есть человекопонятный интерфейс. Продукт же создается не для программистов. Документация для программистов нужна для развития и расширения продукта. А документация пользователя — для использования.
  • @openminded, Не, мои интерфейсы в документации не нуждались :)
  • @Peter, :) Я вот думаю сделать такой листбокс на WPF, который бы выглядел, как такой выдвижной ящик, как в картатеках бывает (в фильме Брюс Всемогущий такой был). Так вот в этом ящике лежат папки с файлами, у папок есть такие "язычки" с названием. И вот пользовател проводит мышой по этим папкам и они типа перелистываются, как пальцами. А потом нажимает по какой-то папке и она достается и раскрывается. Вот для такого листбокса могла бы пригодиться документация.
  • @openminded, :))) Вестимо, а вот для всем знакомого хтмл нет.
  • @Peter, Для батона тоже не нужна. Но вот однажны я проснулся и понял — прокрутка в контролах — зло. Нужно сделать так, чтобы они все помещались на экране и при наведении показывали свое название (разумеется они должны быть упорядочены). Да и автопрокрутка при наведении тоже зло. Скорее всего это навеяно Pivot, где все все все влазит на один экран.