Вопросы с тегом «documentation»

Почему в документации на некоторых языках написано «эквивалентно», а не «есть»? Например, документы Python говорят itertools.chain(*iterables) ... Эквивалентно : def chain(*iterables): # chain('ABC', 'DEF') --> A B C D E F for it in iterables: for element in it: yield element Или эта ссылка на C ++find_if : Поведение этого …

23 c++  python  documentation  compiler 

Закрыто . Этот вопрос должен быть более сфокусированным . В настоящее время не принимает ответы. Хотите улучшить этот вопрос? Обновите вопрос, чтобы он был сосредоточен только на одной проблеме, отредактировав этот пост . Закрыто в прошлом году . Я хочу документировать свой код так, чтобы минимальная потребность в чтении и …

22 documentation  code-reviews  documentation-generation  help-documentation 

Кажется немного спорным предметом документирования всего, включая синтаксис «JavaBean» методов получения и установки полей: люди говорят, что это бесполезно длинный и повторяющийся разрыв DRY (не повторяйте себя) , что соглашение об именах должно объяснять все , и это загромождает код / ​​документацию. Иногда эти аргументы работают. Но в других случаях …

22 documentation 

Я не могу сосчитать, сколько раз я прочитал утверждения в духе «модульные тесты являются очень важным источником документации тестируемого кода». Я не отрицаю, что они правдивы. Но лично я никогда не использовал их в качестве документации, никогда. Для типичных структур, которые я использую, объявления методов документируют их поведение, и это …

22 unit-testing  documentation 

В настоящее время мы пишем функциональные и технические спецификации в формате двух столбцов; Краткое предложение и технические детали. Детали часто относятся к приложению со схемами, схемами дизайна и т. Д. Однако я борюсь с тем, в каком времени писать это: С прошедшим временем, как будто работа сделана, я изо всех …

21 documentation  specifications  writing 

Фон: мои сотрудники и я пишем статью для академического журнала. В ходе нашего исследования мы написали программу моделирования на Java. Мы хотим сделать программу симуляции свободно доступной для использования другими. Мы решили разместить код в репозитории GitHub. Чтобы другим было легко пользоваться, мы хотим написать хорошую документацию для нашей программы, …

20 java  documentation 

Итак, у нас есть такой интерфейс /// <summary> /// Interface for classes capable of creating foos /// </summary> public interface ICreatesFoo { /// <summary> /// Creates foos /// </summary> void Create(Foo foo); /// <summary> /// Does Bar stuff /// </summary> void Bar(); } Недавно мы воспроизвели документацию, в которой рассказывалось …

20 c#  documentation  xml  documentation-generation 

Закрыто . Этот вопрос основан на мнении . В настоящее время не принимает ответы. Хотите улучшить этот вопрос? Обновите вопрос, чтобы ответить на него фактами и цитатами, отредактировав этот пост . Закрыто 6 лет назад . Проведя более года, работая над проектом социальной сети для меня с использованием WordPress и …

19 documentation  hiring  outsourcing  knowledge-transfer  wordpress 

Иногда, хотя и не часто, мне приходится включать математическую логику в мой код. Используемые концепции в основном очень просты, но результирующий код не таков - множество переменных с неясной целью и некоторые операции с не столь очевидным намерением. Я не имею в виду , что код не читается или неосновательный, …

19 java  documentation  math 

Недавно я работал над рефакторингом частей базы кода, с которыми я сейчас работаю, - не только для того, чтобы лучше понять это, но и для того, чтобы облегчить работу тех, кто работает над кодом. Я склонен полагать, что самодокументированный код - это хорошо . Я просто думаю, что это чище, …

18 java  documentation  refactoring  javadocs 

Закрыто . Этот вопрос основан на мнении . В настоящее время не принимает ответы. Хотите улучшить этот вопрос? Обновите вопрос, чтобы ответить на него фактами и цитатами, отредактировав этот пост . Закрыто 5 лет назад . Всем известно, что хорошо документированная разработка программного обеспечения ведет к успеху. Однако обычно это …

18 documentation  wiki 

Предположим, что вы единственный разработчик, уходящий с работы. Какую информацию / материал, помимо самого кода, вы должны создать и оставить для замены? Очевидный ответ: «все, что вы хотели бы получить на новой работе», конечно, но прошло уже много времени с тех пор, как я начал новую работу, и я забыл, …

18 documentation  knowledge-transfer 

Я изучал способы более формального документирования программных проектов и узнал о IEEE 830-1998: рекомендуемая практика для спецификаций требований к программному обеспечению . Однако, как видно из этой ссылки, она была заменена. Я знаю, что 830-1998, и, возможно, даже 830-1993, вероятно, просто хороши для использования. Однако, если ничего другого, я хотел …

17 documentation  requirements  standards 

Мы все видели бесчисленные примеры программного обеспечения, которое поставляется с «минимальными системными требованиями», например: Windows XP / Vista / 7 1 ГБ ОЗУ 200 МБ для хранения Как они вообще определяются? Очевидно, что иногда существуют определенные ограничения (если программа занимает 200 МБ на диске, то это жесткое требование). Помимо этих …

17 documentation  requirements  qa 

Один из разработчиков в моей команде считает, что необходимо написать комментарий javadoc для КАЖДОГО параметра в сигнатуре метода. Я не думаю, что это необходимо, и на самом деле я думаю, что это может быть даже вредно. Прежде всего, я думаю, что имена параметров должны быть описательными и самодокументируемыми. Если не …

17 java  documentation  source-code  comments  maintainability