Вы составляете отчет по практике и у вас есть такой материал, который достаточно объемен, но информативно важен, разъясняет, детализирует те или иные аспекты отчета по практике, показывать алгоритм действий в процессе практической работы, тогда включите его в Приложение.
Обычно к такому материалу относится:
- отсканированные документы, касающиеся деятельности организации, где вы проходили практику (например, устав, бухгалтерский баланс, схема организационной структуры);
- различные ГОСТы, Положения о работе организации;
- математические формулы, расчеты, доказательства,
- таблицы, графики, диаграммы и другой иллюстративный, графический материал вспомогательного и дополнительного характера,
- инструкции, протоколы, методики, методы исследования,
- анкеты, опросы,
- примеры задач и индивидуальных заданий, которые необходимо было выполнить в процессе обучения;
- справочные материалы (образцы документов, статистика, отчеты и т.д.).
По общепринятому правилу, а также руководствуясь ГОСТами, Приложения в отчете по практике оформляются после Списка использованных источников. Но не лишним будет отметить, что наличие этого раздела не является обязательным требованием. В зависимости от типа практики (преддипломная, учебная, производственная), ее тематики, направления и т.д. студент (совместно, конечно, с руководителем практики) сам решает, писать Приложение или нет.
Почему техническая документация — это интересно
Как же правильно оформить Приложение к отчету по практике и где можно посмотреть пример? Содержательное наполнение и правила оформления Приложений регулируются:
- методическими рекомендациями вашего ВУЗа,
- ГОСТ 7.32 – 2001 «Отчет о научно-исследовательской работе. Структура и правили оформления».
Если вы начали оформлять Приложение в отчете, не торопитесь сразу обращаться к ГОСТам. Чаще всего для преподавателя главнее оказываются вузовские рекомендации, а не государственные стандарты, поэтому надо все-таки посмотреть тот образец Приложений, который принят в вашем ВУЗе.
Правильно оформлять Приложения в отчете помогут общепринятые требования, основанные на ГОСТах:
1. Выберите один из предлагаемых ГОСТами способов того, как можно оформить Приложения:
- как продолжение текста отчета (с продолжением сквозной нумерации страниц),
- как отдельный самостоятельный документ (с новой нумерацией страниц).
2. Обязательно делайте в тексте отчета ссылки на каждое из приложений. Лишние приложения из категории «Я думал, пригодится!» не допускайте в работе. Располагайте приложения в соответствии с порядком расположения ссылок на них, то есть первая ссылка – первое Приложение А, вторая ссылка – второе Приложение Б.
3. Начинайте каждое приложение с новой страницы. Посредине страницы пишется с заглавной буквы слово Приложение и обозначается заглавными буквами русского алфавита, начиная с буквы «А» (кроме букв Ь, Ы, Ъ, Ё, О, Ч, З, Й). Допускается использование латиницы, но не I и O.
Как документировать код | Doxygen урок
4. Сформулируйте к каждому приложению заголовок, который оформляется отдельной строкой, симметрично относительно основного текста, с заглавной буквы, без кавычек.
5. Обязательно узнайте, каковы требования оформления Приложения в вашем ВУЗе. В них может быть прописано требование нумеровать, а не подписывать буквами приложения в отчете, употреблять знак «№», располагать слово «Приложение» и его заголовок посредине страницы или в правом углу.
6. При необходимости разделите Приложение на разделы, пункты и т. д. В подобном случае каждую часть фиксируют номером, а буквенное обозначение надо вставить перед ним (образец: Приложение М 1.2).
7. Если приложение заканчивается на второй странице, то вставьте указание о том, что это Окончание Приложения М 1.2. Если приложение занимает 3 и более страницы, то на последней отметьте, что это Окончание Приложения М, а на предыдущих – Продолжение Приложения М.
8. Используйте единообразный принцип оформления всех приложений.
10. Не переусердствуйте с количеством приложений, все должно быть в меру. Оптимальное количество, обычно рекомендуемое в методической литературе, – до 5. Это еще раз уточните на вашей кафедре. И помните: все приложения должны быть информативно необходимы в отчете по практике. Не стоит копировать все имеющиеся в организации документы и включать их в отчет.
Подпишитесь на нас в ВК.
Публикуем полезные лайфхаки для учёбы
Источник: www.akademik.help
Документирование API
При фразе «Документирование API» многие приходят в ужас, так как, на первый взгляд, это кажется очень трудным, страшным и тяжёлым. Документ по ГОСТу сразу кажется небольшой детской сказкой на этом фоне. Но не так страшен чёрт, как его малюют! Я не говорю, что документирование API — это легко и просто.
Да этому нельзя научиться из одной короткой статьи или видео, но если придёт понимание этой темы, то и на изучение этой темы уйдёт гораздо меньше времени. Да–к, что же такое API? И как его задокументировать? В данной статье рассмотрена эта очень непростая тема.
Что такое API?
API (application programming interface) — это набор готовых классов, функций, процедур, структур и констант, предоставляемые самим приложением или операционной системой для взаимодействия с внешними программами.
Например, у вас есть кот Барсик, который любит лежать на обеденном столе. Вам это не нравится. Вы говорите Барсику: «Барсик, брысь со стола!». Барсик хоть и нехотя, но слезает со стола. Так вот, API — это набор команд, благодаря которым кот Барсик понял хозяина, что ему следует слезь со стола.
Другой пример, если программу (модуль, библиотеку) рассматривать как чёрный ящик, то API — это множество «ручек», которые доступны пользователю данного ящика и которые он может вертеть и дёргать.
При этом пользователю необязательно понимать и знать, что такое API. API это «язык» общения между двумя программами и необходим программистам. API создаётся чтобы приложения созданные разными разработчикам корректно существовали вместе и могли взаимодействовать друг с другом.
Компоненты образуют иерархию, в результате которой высокоуровневые компоненты используют API низкоуровневых компонентов, а те, в свою очередь, используют API ещё более низкоуровневых компонентов. По такому принципу построены протоколы передачи данных по Интернет. Каждый уровень пользуется функциональностью предыдущего («нижележащего») уровня и, в свою очередь, предоставляет нужную функциональность следующему («вышележащему») уровню.
На рисунке ниже представлена схема СЭД «Кодекс: Документооборот», в которой отображено API для внешних систем, а также для внутренних в данной СЭД.
API библиотеки функций и классов включает в себя описание сигнатур и семантики функций.
Сигнатура функции
Сигнатура функции — это часть общего объявления функции, позволяющая средствам трансляции идентифицировать функцию среди других. В различных языках программирования существуют разные представления о сигнатуре функции, что также тесно связано с возможностями перегрузки функций в этих языках.
Например, в языке программирования C++ простая функция однозначно опознаётся компилятором по её имени и последовательности типов её аргументов, что составляет сигнатуру функции в этом языке. Если функция является методом некоторого класса, то в сигнатуре будет участвовать и имя класса.
В языке программирования Java сигнатуру метода составляет его имя и последовательность типов параметров; тип возвращаемого значения в сигнатуре не участвует.
В СЭД «Кодекс: Документооборот» используется API на основе web-технологий REST-API, на её примере рассмотрим формирование вызова любого GETPOST запроса.
Пример формирования вызова любого GETPOST запроса
//на вход принимаются url запроса, метод (GET/POST), токен, и объект, который необходимо //передать, если это POST public static byte[ ] CreateRequest(string url, string method, string token, Object obj) HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url); request.
Method = method; //Помещаем токен в заголовок request.Headers.Add(«Token», token); // Если POST – записываем передаваемый объект if (request.
Method == «POST») UTF8Encoding encoding = new UTF8Encoding(); string jsonString = JsonConvert.SerializeObject(obj); var bytes = encoding.
GetBytes(jsonString); request.ContentType = «application/json»; request.ContentLength = bytes.Length; using (var newStream = request.
GetRequestStream()) newStream.Write(bytes, 0, bytes.Length); newStream.
Close(); > > try //Получаем ответ от сервиса HttpWebResponse httpWResponse = (HttpWebResponse)request.GetResponse(); using (MemoryStream mstr = new MemoryStream()) httpWResponse.
GetResponseStream().CopyTo(mstr); //возвращаем полученный с сервиса объект в виде массива байт return mstr.ToArray(); > > catch (WebException ex) //обрабатываем исключения var stCode = ((HttpWebResponse)ex.Response).StatusCode; > return null; >
Семантика функции
Семантика функции — это описание того, что данная функция делает. Семантика функции включает в себя описание того, что является результатом вычисления функции, как и отчего этот результат зависит. Обычно результат выполнения зависит только от значений аргументов функции, но в некоторых модулях есть понятие состояния. Полным описанием семантики функций является исполняемый код функции или математическое определение функции.
Ниже, для примера, рассмотрена одна из функций СЭД «Кодекс: Документооборот».
/Documents/GetDocLinkedObjects GET
Возвращает список связанных документов по переданному идентификатору.
Таблица 1 — Идентификатор документа
| Параметр | Тип | Описание |
| uid | Guid | Идентификатор документа |
Возвращаемое значение – список связей с документом.
Таблица 2 — Список связей с документом
| Свойство | Тип | Описание |
| DocUID | Guid | Идентификатор связанного элемента |
| DirectionType | DirectionType | Тип связанности (тип подчинения) |
| LinkType | Integer | Идентификатор типа связи (из справочника LINK_TYPES) |
| LinkTypeName | String | Наименование типа связи |
| OperatorUID | Guid | Идентификатор автора, создавшего связь |
Проблема документирования API
Документация API — это техническая (программная) документация, в которой указано как использовать API.
При этом эту документацию нужно поддерживать в актуальном стоянии чаще, чем любую другую. Ведь от актуальности документации API зависит качество разработки продукта. Однако, есть еще проблема разработки самого API системы. Любая система развивается, добавляются функции, изменяются существующие вызовы и методы.
Но необходимо помнить о том, что с нашей системой могут быть интегрированы другие системы. И если изменения затронут API, то такая интеграция «развалится», при следующем обновлении произойдёт нарушение механизмов взаимодействия. Поэтому в документировании API можно выделить две основные проблемы:
- Сложность написания документации API, так как это очень трудная тема. Неясно как писать, что писать и прочее. При написании возникает очень много вопросов. Тем более, если человек до этого никогда не имел дело с документированием API.
- Поддержка документации API в актуальном состоянии.
Проблема стандартизации API
В первую очередь с документацией API будут работать люди. В связи с этим, для общего понимания нужен некий стандарт разработки API, чтобы разработчики даже при беглом ознакомлении понимали, как с ним корректно взаимодействовать. Также наличие стандарта API позволяет использовать средства автоматической кодогенерации, что существенно повышает скорость разработки, но об этом я расскажу позже.
Подобного рода внутренний стандарт лучше разработать и утвердить с отделом разработки программного обеспечения.
Для примера документация API должна включать:
- Пример полного запроса.
- Примеры ожидаемого ответа.
- Список кодов ошибок.
- Удобный для поиска Web–интерфейс.
- Предупреждения об изменении версии и расписание устаревания.
Способы создания документации API
- Создать текстовый документ.
Это, конечно, самый простой вариант, в котором можно сделать максимально подборные описания, но такой документ сложно поддерживать в актуальном состоянии, на его создание уйдёт куча времени, да и использовать его в других сферах (например, тестирование) нельзя. - Создать документацию с помощью специализированных программ (спецификаций).
Их нельзя сделать такими подробными, как тестовый документ, но зато можно настроить автогенерацию (изменение кода приложения документации автоматически с учётом изменений), которая позволит быть документации API всегда в актуальном состоянии, что очень важно. Поэтому сейчас большинство компаний выбирает именно этот способ. Повторюсь, ведь от актуальности документации API зависит качество разработки ПО.
Одни из самых популярных спецификаций — это RAML, Swagger и API Blueprint.
Например, если программирование Системы происходи в MS Visual Studio, то в ней автоматически генерируется Xml (представлена на картинке ниже), с помощью которой уже можно создать в любой другой спецификации документацию API.
В данной статье разберём спецификацию Swagger, так как, на мой взгляд, она является более удобной для работы.
Когда понимание документирование API будет «на уровне», то можно уже выбрать любую другую программу, которая нравится больше, а для начала можно начать и с Swagger.
Swagger
Для учебных целей можно открыть Swagger Editor, в котором можно попробовать создавать документацию API.
Сайт: http://editor.swagger.io/
Swagger Editor состоит из двух блоков: код (слева), документация API (блок справа (зависит от блока слева)).
Код
Типы аннотаций, использованные для описания методов:
- Get — означает, что для доступа к методу должен использоваться http-метод GET. Существуют аналогичные аннотации для всех http-методов: Post, Put и другие.
- Parameter — используется для описания параметров метода.
- Response — используется для описания ответа API.
- Schema — используется для описания формата выходных данных.
Документация API
В Swagger генерация происходит автоматически.
Полученная документация содержит описание всех типов данных, возвращаемых API, список доступных методов c подробным описанием.
Описание метода API содержит его url, описание всех параметров, а также все варианты ответов. Т.к. мы ссылались на модель Post в описании ответа, мы можем видеть ссылку на эту модель и даже пример ответа API, сгенерированный на основании описания модели.
В заключении хотелось бы сказать, что документированию API невозможно научиться по одной статье, тут нужна куда более сильная теории и много практики. У вас обязательно должен быть человек, который вам поможет, подскажет и укажет на ваши ошибки. Но не забывайте, что документирование API невозможно без взаимодействия с Отделом разработки ПО. Они помогут установить и настроить программу, подскажут, где и что взять, где и что посмотреть.
Источник: docplace.ru
Как написать документацию к коду в приложении?
Документация кода — это важный элемент любого приложения, который позволяет разработчикам, которые будут использовать ваш код в будущем, быстро понимать его работу и использование. Вот несколько шагов для написания документации:
2. Начните с обзора приложения: начните с обзора приложения и как ваш код взаимодействует с другими частями приложения.
3. Опишите каждую функцию и метод: для каждой функции или метода, напишите краткое описание каждого параметра, что они делают и что возвращают.
4. Приведите примеры использования: для каждого метода или функции приведите примеры использования, рассказывая о том, как они могут быть использованы в реальном приложении.
5. Обновляйте документацию: документация должна быть обновлена каждый раз, когда вы вносите изменения в код, чтобы убедиться, что она всегда актуальна.
Важно помнить, что хорошо написанная документация может сэкономить много времени и усилий другим разработчикам, которые будут использовать ваш код в будущем.
Похожие записи:
- Как написать документацию к коду на Java?
- Как писать документацию к коду на Python?
- Как создать удобочитаемую документацию к коду на Python?
- Как правильно писать документацию к TypeScript коду?
- Как писать документацию к коду в Delphi?
Источник: qaa-engineer.ru