Что такое файл кода
Отдельные элементы (слова) в строке.
Ниже приведен пример стиля code .
Используйте формат кода при ссылке на именованные параметры и переменные в ближайшем блоке кода в тексте. Формат кода также можно использовать для свойств, методов, классов и ключевых слов языка. Дополнительные сведения см. в разделе Элементы кода далее в этой статье.
Блоки кода в файле Markdown, содержащем статью.
Используйте встроенные блоки кода, когда непрактично отображать код по ссылке на файл кода. Дополнительные сведения см. в разделе Блоки кода далее в этой статье.
Блоки кода с использованием ссылки на файл кода в локальном репозитории.
Дополнительные сведения см. в разделе Ссылки на фрагменты кода в репозитории далее в этой статье.
Блоки кода с использованием ссылки на файл кода в другом репозитории.
Дополнительные сведения см. в разделе Ссылки на фрагменты кода вне репозитория далее в этой статье.
Блоки кода, которые позволяют пользователю выполнять код в браузере.
Дополнительные сведения см. в разделе Интерактивные фрагменты кода далее в этой статье.
Помимо описания синтаксиса Markdown для каждого метода включения кода, в статье приведено общее руководство для всех блоков кода.
Что такое грамотное программирование?
Грамотное программирование – это подход к программированию, при котором код разъясняется с использованием обычного языка наряду с кодом. Это отличается от смежных практик, таких как документация или комментарии к коду, где код первичен, а комментарии и объяснения вторичны. В грамотном программировании же объяснение кода имеет равные права с самим кодом.
Документация фундаментально отделена от кода. Зачастую документацию пишет человек, который не работает над кодом. Это затрудняет реальное понимание того, что делает код.
Таким образом, грамотное программирование служит средством достижения большей прозрачности и ясности кода.
Разработанное в начале 80-х годов Дональдом Кнутом, ученым-компьютерщиком, ныне почетным профессором Стэнфордского университета, грамотное программирование некоторые инженеры откидывают как пережиток гораздо более ранней эпохи вычислительной техники.
Тем не менее, задачи, стоявшие перед пионерами современной программной инженерии, на самом деле не так уж сильно отличаются от нынешних: все, в конце концов, желают писать чистый, внятный код, который люди смогут понять и взаимодействовать с ним позже.
Тот факт, что грамотное программирование имеет аудиторию в ряде сообществ является явным показателем того, что оно все еще имеет ценность. Единственный вопрос заключается в том, есть ли другие плюсы у этого подхода, которые программисты упускают?
Проверка кода
Если вы включаете блоки кода из другого репозитория, обсудите с владельцами стратегию обслуживания кода, чтобы включенный код не перестал работать и не устарел при обновлении версий библиотек, используемых кодом.
Встроенные блоки кода
Используйте встроенные блоки кода, только когда непрактично отображать код по ссылке на файл кода. Как правило, встроенный код сложнее тестировать и обновлять по сравнению с файлом кода, который является частью полного проекта. И встроенный код может опускать контекст, который может помочь разработчику понять и использовать код. Эти рекомендации относятся главным образом к языкам программирования. Встроенные блоки кода также могут использоваться для выходных и входных данных (например, JSON), языков запросов (таких как SQL) и языков сценариев (например, PowerShell).
Есть два способа указать, что раздел текста в файле статьи является блоком кода: заключив его в тройные обратные кавычки (```) или сделав отступ. Отделение является предпочтительным, так как в этом случае можно указать язык. Старайтесь не использовать отступы, потому что с ними просто ошибиться и другому автору будет сложно понять ваше намерение при редактировании статьи.
Языковые индикаторы размещаются сразу же после открытия тройных обратных кавычек, как в следующем примере:
GitHub Flavored Markdown поддерживает разделение блоков кода тильдами (~), а также обратными кавычками (`). Символ, используемый для открытия и закрытия блока кода, должен быть одинаковым в пределах одного блока кода.
Дополнительные сведения о значениях, которые можно использовать в качестве индикаторов языка, см. в разделе об именах и псевдонимах языков.
Если вы используете слово языка или среды после тройных кавычек (```), которые не поддерживаются, такое слово отобразится в заголовке раздела кода на отображенной странице. По возможности используйте индикатор языка или среды во встроенных блоках кода.
При копировании и вставке кода из документа Word убедитесь, что в нем нет изогнутых кавычек, которые являются для кода недопустимыми. Если есть, замените их на обычные кавычки ( ' и " ). В качестве альтернативы можно воспользоваться пакетом Docs Authoring Pack с функцией замены парных кавычек.
Ссылки на фрагменты кода в другом репозитории
Если файл кода, на который необходимо сослаться, находится в другом репозитории, необходимо настроить репозиторий кода в качестве зависимого репозитория. При этом нужно указать его имя. Это имя затем выступает в качестве имени папки, используемого для ссылки на код.
Например, репозиторий документов — Azure/azure-docs, а репозиторий кода — Azure/azure-functions-durable-extension.
В корневой папке azure-docs добавьте следующий раздел в .openpublishing.publish.config.json:
Теперь при добавлении ссылки на sample-durable-functions, как если бы это была папка в azure-docs, вы на самом деле ссылаетесь на корневую папку в репозитории azure-functions-durable-extension.
- Находясь в Visual Studio Code, нажмите клавиши ALT+M или OPTION+M и выберите "Фрагмент кода".
- Вам будет предложено выполнить поиск по всему содержимому, в какой-то области или по различным репозиториям. Выберите поиск по репозиториям.
- Вам будет представлен набор репозиториев из .openpublishing.publish.config.json. Выберите репозиторий.
- Введите условие поиска и найдите нужный файл. Найдя файл, выберите его.
- Затем выберите, какие строки кода нужно включить в фрагмент, используя следующие параметры: ИД, Диапазон или Никакие.
- В зависимости от выбора на шаге 5 предоставьте значение.
Ссылка на фрагмент кода будет выглядеть следующим образом:
В репозитории azure-functions-durable-extension этот файл кода находится в папке samples/csx/shared. Как отмечалось ранее, номера строк для выделения начинаются от начала фрагмента, а не от начала файла.
Имя, назначаемое зависимому репозиторию, указывается относительно корня основного репозитория, но тильда (~) относится к корню набора документов. Корень набора документов определяется build_source_folder в .openpublishing.publish.config.json. Путь к фрагменту кода в предыдущем примере работает в репозитории azure-docs, так как build_source_folder относится к корню репозитория ( . ). Если бы в качестве build_source_folder использовалось articles , путь начинался бы с ~/../samples-durable-functions , а не с ~/samples-durable-functions .
Схемы
Не пугайтесь термина "схема". Схема — это просто XML-файл, содержащий правила для содержимого XML-файла данных. Файлы схем обычно имеют расширение XSD, тогда как для файлов данных XML используется расширение XML.
Схемы могут быть сложными, и в данной статье невозможно объяснить, как их создавать. (Кроме того, скорее всего, в вашей организации есть ИТ-специалисты, которые знают, как это делать.) Однако полезно знать, как выглядят схемы. Следующая схема определяет правила для набора тегов
Не беспокойтесь, если в примере не все понятно. Просто обратите внимание на следующее:
Строковые элементы в приведенном примере схемы называются объявлениями. Если бы требовались дополнительные сведения о животном, например его цвет или особые признаки, то специалисты отдела ИТ добавили бы к схеме соответствующие объявления. Систему XML можно изменять по мере развития потребностей бизнеса.
Объявления являются мощным средством управления структурой данных. Например, объявление означает, что теги, такие как и , должны следовать в указанном выше порядке. С помощью объявлений можно также проверять типы данных, вводимых пользователем. Например, приведенная выше схема требует ввода положительного целого числа для возраста кота и логических значений (TRUE или FALSE) для тегов ALTERED и DECLAWED.
Если данные в XML-файле соответствуют правилам схемы, то такие данные называют допустимыми. Процесс контроля соответствия XML-файла данных правилам схемы называют (достаточно логично) проверкой. Большим преимуществом использования схем является возможность предотвратить с их помощью повреждение данных. Схемы также облегчают поиск поврежденных данных, поскольку при возникновении такой проблемы обработка XML-файла останавливается.
Огороженные блоки кода
При наличии нескольких псевдонимов в пакете Docs Authoring Pack функции завершения языка разработки используется первый допустимый псевдоним.
Идентификаторы
Слова, изобретенные вами. Да, не удивляйтесь! Вы, программист. Эти слова обычно называются идентификаторами. Они могут быть созданы вами или другими программистами. Они упакованы в плагины, более известные как библиотеки.
Примером является библиотека Math. Она позволяет получить доступ к функциям, таким как квадратный корень (Math.sqrt), используемый в JavaScript.
Многие языки программирования поставляются со множеством библиотек. Они обычно называются SDK (комплекты разработки программного обеспечения). Загружаются вместе с компилятором для дальнейшего создания технологий, приложений и проектов. Также существуют фреймворки, созданные, чтобы облегчить разработку проекта и объединить его различные составляющие.
Некоторые идентификаторы в комплекте с выбранным языком не могут использоваться в качестве идентификатора пользователя. Примером является слово string в Java. Такие идентификаторы вместе с ключевыми словами называются Зарезервированными Словами. Они также являются особыми.
Все ключевые слова являются зарезервированными. Также слова, которые вы выбираете, должны иметь смысл для тех, кто впервые их видит.
Заполнители
Если требуется, чтобы пользователь заменил часть отображаемого кода собственными значениями, используйте текст заполнителя, заключенный в угловые скобки. Пример:
Вы можете заметить, что квадратные скобки нужно удалить при замене реальных значений. В руководстве по стилю письма от Майкрософт предлагается использовать курсив, который можно форматировать внутри встроенного кода, заключенного в угловые скобки:
Фигурные скобки <> не рекомендуются для использования в качестве синтаксических заполнителей. Их можно спутать с той же нотацией, которая используется в заменяемом тексте, строках форматирования, интерполяции строк, текстовых шаблонах и подобных конструкциях программирования.
Имена заполнителей можно разделять дефисами (kebab-case), подчеркиванием или не разделяться вообще (Pascal case). Kebab-case может вызывать синтаксические ошибки, а знаки подчеркивания могут конфликтовать с подчеркиванием. Использование всех заглавных букв может вызвать конфликты с именованными константами во многих языках, хотя такой текст также может привлекать внимание к имени заполнителя.
Начало работы: ваша первая программа
- Следуйте приведенным здесь инструкциям, чтобы настроить Python в вашей компьютерной системе.
- Установите простой редактор, чтобы ввести исходный код. Для начала можете использовать этот текстовый редактор.
3. Откройте в нем новый файл и введите следующее:
- Не забудьте сохранить файл как main.py.
- Найдите путь к файлу через CLI и введите следующую команду:
Результат должен выглядеть так:
Встроенные блоки интерактивного кода
Для следующих языков фрагменты кода можно сделать исполняемыми в окне браузера:
Если включен интерактивный режим, в отображаемых полях с кодом будут кнопки Попробовать или Запустить. Например:
отображается следующим образом:
Чтобы включить эту функцию для конкретного блока кода, используйте специальный идентификатор языка. Доступны следующие параметры:
В Azure Cloud Shell и PowerShell Cloud Shell пользователи могут выполнять команды только с собственной учетной записью Azure.
Синтаксис
translation-unit:
external-declaration
translation-unitexternal-declaration
external-declaration:
function-definition
declaration
В статье Общие сведения об объявлениях описывается синтаксис нетерминала declaration , а в справочнике по препроцессору поясняется, как происходит обработка записи преобразования.
Описание соглашений о синтаксисе ANSI вы найдете во введении к статье Общие сведения о синтаксисе языка C.
Компонентами блока трансляции являются внешние объявления, которые включают в себя определения функций и объявления идентификаторов. Эти объявления и определения могут находиться в исходных файлах, файлах заголовков, библиотеках и других файлах, которые необходимы программе. Чтобы создать программу, необходимо скомпилировать каждый блок трансляции и скомпоновать полученный объектный файл.
Исходная программа языка C представляет собой набор директив, директив pragma, объявлений, определений, блоков операторов и функций. Для того чтобы все они были допустимыми компонентами программы на языке Microsoft C, они должны иметь синтаксис, описанный в настоящей книге. При этом они могут находиться в программе в любом порядке (в пределах описанных здесь правил). Однако от расположения этих компонентов в программе зависит то, каким образом в программе будут использоваться переменные и функции. (Дополнительные сведения см. в статье Время существования, область, видимость и компоновка.)
Исходные файлы не должны содержать исполняемых операторов. К примеру, в один исходный файл можно поместить все определения переменных, а затем в другом исходном файле, в котором эти переменные используются, объявить ссылки на них. Этот метод позволяет легко находить и при необходимости изменять определения. По этой же причине константы и макросы часто организуются в отдельные файлы — так называемые включаемые файлы, или файлы заголовка. По мере необходимости на них можно ссылаться из исходных файлов. Сведения о макросах и включаемых файлах см. в справочнике по препроцессору.
Excel для Microsoft 365 Word для Microsoft 365 Outlook для Microsoft 365 PowerPoint для Microsoft 365 Access для Microsoft 365 Visio Online (план 2) Excel 2021 Word 2021 Outlook 2021 PowerPoint 2021 Access 2021 Microsoft Visio профессиональный 2021 Excel 2019 Word 2019 Outlook 2019 PowerPoint 2019 Access 2019 Visio профессиональный 2019 Excel 2016 Word 2016 Outlook 2016 PowerPoint 2016 Access 2016 Visio профессиональный 2016 Office 2016 Excel 2013 Word 2013 Outlook 2013 PowerPoint 2013 Access 2013 Visio 2013 Office 2013 Excel 2010 Word 2010 Outlook 2010 PowerPoint 2010 Access 2010 Visio 2010 Office 2010 Excel 2007 Word 2007 Outlook 2007 PowerPoint 2007 Access 2007 Visio 2007 Office 2007 Еще. Меньше
Вероятно, вы слышали о языке XML и вам известно множество причин, по которым его необходимо использовать в вашей организации. Но что именно представляет собой XML? В этой статье объясняется, что такое XML и как он работает.
В этой статье
Путь к файлу кода
Синтаксис ссылок на фрагменты
Этот синтаксис является блоком расширения Markdown. Он должен использоваться в отдельной строке.
- Язык фрагмента кода. Дополнительные сведения см. в разделе Поддерживаемые языки далее в этой статье.
- Относительный путь в файловой системе, который указывает файл фрагмента кода для ссылки.
- Используются вместе для указания способа получения кода из файла и его отображения:
- range : 1,3-5 Диапазон строк. Этот пример содержит строки 1, 3, 4 и 5.
- id : Create Идентификатор фрагмента, который нужно вставить из файла кода. Это значение не может существовать одновременно с диапазоном.
- highlight : 2-4,6 Диапазон и (или) номера строк, которые должны выделяться в создаваемом фрагменте кода. Нумерация задается относительно отображаемых строк (в соответствии с диапазоном или идентификатором), а не файла.
- interactive : cloudshell-powershell , cloudshell-bash , try-dotnet , try-dotnet-class , try-dotnet-method Строковое значение, определяющее тип используемой интерактивности.
- Сведения о представлении имени тега в исходных файлах фрагмента кода для каждого языка см. в разделе с рекомендациями по DocFX.
Горизонтальные полосы прокрутки
Разбейте длинные строки, чтобы избежать горизонтальных полос прокрутки. Полосы прокрутки в блоках кода затрудняют его чтение. Это особенно проблематично в более длинных блоках кода, где невозможно одновременно показать полосу прокрутки и строку, которую необходимо прочитать.
Чтобы свести к минимуму горизонтальные полосы прокрутки в блоках кода, рекомендуется разбивать строки кода, длиннее 85 символов. Но помните, что присутствие или отсутствие полосы прокрутки не является единственным критерием удобочитаемости. Если разбивка длинной строки затрудняет чтение или удобство копирования и вставки, строка может быть длиннее 85 символов.
Полужирный стиль
В более старых руководствах по стилю для встроенного кода используется полужирный шрифт. Полужирный шрифт можно использовать, когда стиль кода настолько перегружен, что его трудно читать. Например, таблица Markdown со множеством элементов кода может выглядеть перегруженной, если везде применять стилизацию кода. Если выбрано использование полужирного начертания, используйте синтаксис нелокализованных строк, чтобы код не был локализован.
Выбранные номера строк
В этом примере отображаются только строки 2–24 и 26 из файла кода StudentController.cs.
Предпочтительнее использовать именованные фрагменты кода, а не жестко заданные номера строк, как описано в следующем разделе.
XML в системе Microsoft Office
Профессиональные выпуски Office обеспечивают всестороннюю поддержку XML. Начиная с Microsoft Office 2007, в Microsoft Office используются форматы файлов на основе XML, например DOCX, XLSX и PPTX. Поскольку XML-данные хранятся в текстовом формате вместо запатентованного двоичного формата, ваши клиенты могут определять собственные схемы и использовать ваши данные разными способами без лицензионных отчислений. Дополнительные сведения о новых форматах см. в сведениях о форматах Open XML и расширениях имен файлов. К другим преимуществам относятся:
Меньший размер файлов. Новый формат использует ZIP и другие технологии сжатия, поэтому размер файла на 75 процентов меньше, чем в двоичных форматах, применяемых в более ранних версиях Office.
Более простое восстановление данных и большая безопасность. Формат XML может быть легко прочитан пользователем, поэтому если файл поврежден, его можно открыть в Блокноте или другой программе для просмотра текста и восстановить хотя бы часть данных. Кроме того, новые файлы более безопасны, потому что они не могут содержать код Visual Basic для приложений (VBA). Если новый формат используется для создания шаблонов, то элементы ActiveX и макросы VBA находятся в отдельном, более безопасном разделе файла. Кроме того, можно удалять личные данные из документов с помощью таких средств, как инспектор документов. Дополнительные сведения об использовании инспектора документов см. в статье Удаление скрытых и персональных данных при проверке документов.
Пока все хорошо, но что делать, если у вас есть данные XML без схемы? У Office программ, которые поддерживают XML, есть свои подходы к работе с данными. Например, Excel выдаст схему, если вы откроете XML-файл, который еще не имеет такой схемы. Excel затем вы можете загрузить эти данные в XML-таблицу. Для сортировки, фильтрации или добавления вычислений в данные можно использовать XML-списки и таблицы.
Интерактивные фрагменты кода
Выделение
Фрагменты кода обычно содержат больше кода, чем необходимо для предоставления контекста. Чтобы улучшить читаемость, рекомендуется выделить ключевые строки, на которых нужно сконцентрировать внимание во фрагменте кода, как показано в следующем примере:
Если код включен в файл Markdown статьи, его не удастся выделить. Выделение поддерживается только для фрагментов кода, включенных с помощью ссылки на файл кода.
Фрагменты кода, включаемые по ссылке
Для фрагментов кода, включаемых по ссылке, можно включить интерактивный режим. Чтобы включить эту функцию для конкретного блока кода, используйте атрибут interactive . Допустимые значения атрибута:
Ниже приведены некоторые примеры:
В Azure Cloud Shell и PowerShell Cloud Shell пользователи могут выполнять команды только с собственной учетной записью Azure.
- Без формирования шаблонов ( try-dotnet ). Блок кода должен представлять полный текст программы. Например, допустимым будет файл Program.cs, созданный dotnet new console . Это удобно для демонстрации программы небольшого размера целиком, включая все необходимые директивы using . Операторы верхнего уровня сейчас не поддерживаются.
- Формирование шаблонов методов ( try-dotnet-method ). Блок кода должен представлять содержимое метода Main в консольном приложении. Вы можете учитывать директивы using , добавленные шаблоном dotnet new console . Этот вариант удобен для коротких фрагментов кода, которые демонстрируют использование одной функции.
- Формирование шаблонов классов ( try-dotnet-class ). Блок кода должен представлять класс с методом Main , который выполняет для программы роль точки входа. Этот вариант можно использовать для демонстрации взаимодействия между элементами класса.
Элементы кода
"Элемент кода" является ключевым словом языка программирования, именем класса, именем свойства и т. д. Не всегда очевидно, что рассматривается в качестве кода. Например, имена пакетов NuGet должны считаться кодом. Если возникают сомнения, ознакомьтесь с рекомендациями по форматированию текста.
Операторы
Шансы, что вы будете писать исходный код для выполнения какой-нибудь операции, крайне высоки. Любые языки программирования, которые мы используем, включают в себя множество операторов. Среди применяемых выделяют сложение (+), деление (/) умножение (*), вычитание (-) и знак больше (>).
Операторы обычно классифицируются следующим образом:
- Операторы присваивания. Они иногда истолковываются как equals, что неправильно. Равенство используется для сравнения двух значений. А вот оператор присваивания присваивает значение переменной, например pet_name = 'Hippo'
- Арифметические операторы. Состоят из операторов для выполнения арифметических задач, таких как сложение и вычитание. Некоторые языки программирования предоставляют арифметические операторы, когда другие могут их не иметь в своем арсенале. Например, оператор модуля/остатка (%) возвращает остаточное значение в операциях деления.
- Реляционные операторы. Используются для сравнения значений. Они включают в себя больше, меньше, равно, не равно. Их представление также зависит от того, какой язык программирования вы изучаете. Для некоторых ЯП не равно – это <>, для других же – != или !==.
- Логические операторы. Применяются для произведения логических операций. Обычно используемыми логическими операторами являются и, или, нет. Некоторые языки представляют эти операторы в виде специальных символов. Например, && для представления логического и, || – для или, и ! – для нет. Логические значения принято оценивать с помощью булевых значений true или false.
Блоки кода
Синтаксис для включения кода в документ зависит от того, где находится код:
Ниже приведены рекомендации, которые применяются для всех трех типов блоков кода:
Включение средств XML в Office
По умолчанию вкладка "Разработчик" не отображается. Ее необходимо добавить на ленту для использования команд XML в Office.
В Office 2016, Office 2013 или Office 2010: Отображение вкладки "Разработчик".
Встроенные стили кода
Чтобы включить элемент кода в текст статьи, поместите его между одинарными кавычками в виде обратного апострофа (`), чтобы указать стиль кода. Встроенный стиль кода не должен использовать формат тройных кавычек.
Markdown Отображение По умолчанию Entity Framework интерпретирует свойство с именем Id или ClassnameID как первичный ключ. По умолчанию Entity Framework интерпретирует свойство с именем Id или ClassnameID как первичный ключ. При локализации статьи (переводе на другие языки) текст, имеющий стиль кода, не переводится. Если вы хотите предотвратить локализацию без использования стиля кода, см. раздел Нелокализованные строки.
Основные типы данных
Исходный код – сосредоточение разных типов даннх: числа (3, 5.7, -100, 3.142) и символы (M, A). В некоторых языках программирования числа разбиваются на подтипы, такие как integers (целые числа).
Целые числа могут быть знаковыми и беззнаковыми, большими и малыми. Последние фактически зависят от объема памяти, зарезервированного для таких чисел. Есть числа с десятичными частями, обычно называемые double и float, в зависимости от языка, который вы изучаете.
Также существуют логические типы данных boolean, которые имеют значение true или false.
Почему грамотное программирование важно сегодня?
Несмотря на очевидные недостатки этого подхода – его стоимость и отсутствие возможности изменять написанную программу, грамотное программирование может стать невероятно мощным навыком для разработчиков программного обеспечения, работающих в самых разных контекстах. Как показывает опыт Франушича по написанию постов в блоге компании Twilio, оно может быть полезным, позволяя вам объединить рассказ и код в одном месте.
Франушича особенно недвусмысленно говорит о его ценности: «Изучение грамотного программирования сделает вас более успешным программистом. Это также поможет вам писать более качественный код, за что ваше будущее «я» будет вам очень благодарно.
Рэмси повторил это мнение в более взвешенных выражениях: « Это действительно заставляет вас думать, прежде чем писать код » .
Ценность этой вынужденной саморефлексии невозможно недооценить. Да, грамотное программирование должно помочь вам писать более качественный код, но оно также побуждает вас думать о том, почему вы делаете то, что делаете. Почему так, а не иначе? Почему я сделал это так, а не иначе?
Хотя вы можете и не начать использовать грамотное программирование в повседневной работе, изучение инструмента, который может дать вам новый взгляд на программирование, может быть только положительным моментом.
Выделение выбранных строк
В примере выделены строки 2 и 5, если считать от начала отображаемого фрагмента кода. Подсчет выделяемых номеров строк не начинается от начала файла кода. Другими словами, выделяются строки 3 и 6 файла кода.
Грамотное статистическое программирование
Возможно, наиболее часто грамотное программирование сегодня можно обнаружить в статистике и науке о данных.
Этот способ, чаще называемый грамотным статистическим программированием, особенно удобен не только из-за сложной математики, которая является неотъемлемой частью статистического программирования, но и из-за потребности в совместном использовании кода и уточнении того, как статистическая программа выдает свои результаты. Это также имеет особый смысл, если учесть, что статистические вычисления – это практика, которая часто встречается в исследовательской среде.
Jupyter Notebooks, как упоминалось выше, является особенно популярным инструментом, который можно рассматривать как реконтекстуализацию грамотного программирования. Хотя вы, возможно, и не догадывались об этом – ни на странице проекта в Википедии, ни на его домашней странице нет никаких намеков на грамотное программирование – признание тайной истории инструмента, который вы можете использовать каждый день, в какой-то мере важно.
Это помогает осознать тайные проблемы и идеи, способствовавшие его созданию, и, может быть, даже способствует возникновению некоторой формы солидарности с другими. В свою очередь, это может способствовать более глубокому самоанализу инженерной практики и подходов.
Франушич направил The New Stack на один из своих любимых репозиториев Jupyter Notebook, созданный Питером Норвигом, сотрудником Стэнфорда и директором по инженерным вопросам в Google. « Если вы не видели эти блокноты, я советую вам познакомиться с ними, чтобы понять, насколько убедительной может быть грамотная программа » .
Они действительно таковыми являются; каждая из них – это своего рода повествование о решении проблем, объединяющее кодера и рассказчика таким образом, чтобы сделать нечто большее, чем просто « показать свою работу » . В Jupyter Notebook Норвиг также может пояснить, почему он делает то, что делает. Это миниатюрные драмы, построенные на триумвирате человека, проблемы и кода.
Пробелы и вкладки
Это пробелы, созданные между кодом, который вы пишете. Они ставятся при нажатии пробела или клавиши табуляции на клавиатуре.
Преобразования
Как говорилось выше, XML также позволяет эффективно использовать и повторно использовать данные. Механизм повторного использования данных называется преобразованием XSLT (или просто преобразованием).
Вы (или ваш ИТ-отдел) можете также использовать преобразования для обмена данными между серверными системами, например между базами данных. Предположим, что в базе данных А данные о продажах хранятся в таблице, удобной для отдела продаж. В базе данных Б хранятся данные о доходах и расходах в таблице, специально разработанной для бухгалтерии. База данных Б может использовать преобразование, чтобы принять данные от базы данных A и поместить их в соответствующие таблицы.
Сочетание файла данных, схемы и преобразования образует базовую систему XML. На следующем рисунке показана работа подобных систем. Файл данных проверяется на соответствие правилам схемы, а затем передается любым пригодным способом для преобразования. В этом случае преобразование размещает данные в таблице на веб-странице.
В следующем примере кода показан один из способов написания преобразования. Она загружает данные в таблицу на веб-странице. В этом примере суть не в том, чтобы показать, как написать преобразование, а в том, чтобы показать одну форму, которую может принять преобразование.
В этом примере показано, как может выглядеть текст одного из типов преобразования, но помните, что вы можете ограничиться четким описанием того, что вам нужно от данных, и это описание может быть сделано на вашем родном языке. Например, вы можете пойти в отдел ИТ и сказать, что необходимо напечатать данные о продажах для конкретных регионов за последние два года, и что эти сведения должны выглядеть так-то и так-то. После этого специалисты отдела могут написать (или изменить) преобразование, чтобы выполнить вашу просьбу.
Корпорация Майкрософт и растущее число других компаний создают преобразования для различных задач, что делает использование XML еще более удобным. В будущем, скорее всего, можно будет скачать преобразование, отвечающее вашим потребностям без дополнительной настройки или с небольшими изменениями. Это означает, что со временем использование XML будет требовать все меньше и меньше затрат.
Двигаемся дальше
Вы познакомились с исходным кодом и изучили его содержимое. Скомпилированный или преобразованный код может не запускаться по ряду причин. Эти причины обычно связаны с ошибками. Действие поиска и удаления ошибок называется отладкой и является навыком, который вы должны изучить. Ошибки мы рассмотрим в следующей части.
Убедитесь, что вы правильно настроили Python в своей компьютерной системе, и запустите свою первую программу.
Добавление метаданных в записную книжку
Присвойте ячейке имя, добавив метаданные ячейки в записную книжку Jupyter.
- В Jupyter вы можете редактировать метаданные ячейки, сначала включив панель инструментов ячейки. Для этого выберите Просмотр > Панель инструментов ячейки > Редактировать метаданные.
- После включения панели инструментов ячейки выберите Изменить метаданные в ячейке, которой нужно присвоить имя.
- Кроме того, можно изменить метаданные непосредственно в структуре JSON записной книжки.
В метаданных ячейки добавьте атрибут "name":
Вы можете добавить любые другие метаданные, которые помогут отслеживать использование ячейки. Пример:
Эволюция нового подхода
Но прежде чем приступить к этому, стоит взглянуть на то время, в котором возникло грамотное программирование. В течение многих лет после того, как Кнут впервые представил этот метод, им заинтересовалось небольшое, но увлеченное сообщество инженеров и компьютерных ученых.
Норман Рэмси, профессор информатики в Университете Тафтса, рассказал изданию The New Stack, как он познакомился с грамотным программированием, когда был техническим руководителем группы инженеров, работавших на американского государственного подрядчика.
Мы подписали контракт с ВВС на поставку программного обеспечения для проверки, и математика, лежащая в основе того, что мы разрабатывали, была довольно сложной.
Сложная математика, лежавшая в основе проекта, привела Рэмси и его команду к грамотному программированию. Это произошло потому, что сама природа грамотного программирования даёт возможность показать свою работу в тексте рядом с исходным кодом. Это позволяет упорядочить свои мысли и ясно изложить свою методику.
Если WEB – первый инструмент Кнута для грамотного программирования – был написан на Паскале, а CWEB, созданный Кнутом вместе с математиком Сильвио Леви, на Си, то проект, который Рэмси и его коллектив выполняли для ВВС, должен был быть написан на языке Ada. Это побудило Рэмси разработать Spidery WEB – инструмент, который позволял инженерам « красиво печатать » на языках, выходящих за рамки тех, которые ранее были в центре внимания сообщества грамотных программистов. В итоге работа Рэмси позволила сделать грамотное программирование более заметным и доступным.
После Spidery WEB Рэмси создал Noweb, возможно, один из самых распространенных инструментов, который позволяет людям заниматься грамотным программированием независимо от конкретного языка программирования.
Его главные достоинства, – утверждается в тексте на сайте проекта, – это простота, расширяемость и независимость от языка – особенно ощутимые по сравнению с другими инструментами грамотного программирования.
Это был интересный обзор того, как развивалась инженерная практика в то время, которое мы можем считать самыми ранними годами современной компьютерной науки: разнообразная смесь личностей с различными мотивами и интересами, работающих вместе, чтобы обнаружить новые способы выполнения задач.
Сегодня часто игнорируется этот аспект технологических инноваций, но мы должны помнить, что именно это сочетание изобретательности и контекстной удачи – правильное место, правильное время – способствует изменениям.
Комментарии
Документация будет важным аспектом деятельности в сфере программирования. Это то, как вы объясняете свой код другим программистам. Подобное делается с помощью комментариев, которые добавляются к различным частям кода. С помощью комментариев вы можете направлять других программистов через написанную программу.
Компилятор игнорирует строки кода, которые являются комментариями.
Вот пример комментария в Python:
Переменные
Переменные – это просто имена областей памяти. Иногда нужно сохранить данные в исходном коде в месте, откуда их можно вызвать, чтобы использовать. Обычно это место памяти, которое резервирует компилятор/интерпретатор. Нам нужно дать имя этим ячейкам памяти, чтобы потом их вспомнить. Рассмотрим фрагмент кода Python ниже:
pet_name – пример переменной, и тип данных, хранящихся в pet_name, является строкой, что делает переменную строковой. Существуют также числовые. Таким образом, переменные классифицируются по типам данных.
Отличительные черты XML
Документы в форматах HTML и XML содержат данные, заключенные в теги, но на этом сходство между двумя языками заканчивается. В формате HTML теги определяют оформление данных — расположение заголовков, начало абзаца и т. д. В формате XML теги определяют структуру и смысл данных — то, чем они являются.
При описании структуры и смысла данных становится возможным их повторное использование несколькими способами. Например, если у вас есть блок данных о продажах, каждый элемент в котором четко определен, то можно загрузить в отчет о продажах только необходимые элементы, а другие данные передать в бухгалтерскую базу данных. Иначе говоря, можно использовать одну систему для генерации данных и пометки их тегами в формате XML, а затем обрабатывать эти данные в любых других системах вне зависимости от клиентской платформы или операционной системы. Благодаря такой совместимости XML является основой одной из самых популярных технологий обмена данными.
Учитывайте при работе следующее:
HTML нельзя использовать вместо XML. Однако XML-данные можно заключать в HTML-теги и отображать на веб-страницах.
Возможности HTML ограничены предопределенным набором тегов, общим для всех пользователей.
Правила XML разрешают создавать любые теги, требуемые для описания данных и их структуры. Допустим, что вам необходимо хранить и совместно использовать сведения о домашних животных. Для этого можно создать следующий XML-код:
Как видно, по тегам XML понятно, какие данные вы просматриваете. Например, ясно, что это данные о коте, и можно легко определить его имя, возраст и т. д. Благодаря возможности создавать теги, определяющие почти любую структуру данных, язык XML является расширяемым.
Но не путайте теги в данном примере с тегами в HTML-файле. Например, если приведенный выше текст в формате XML вставить в HTML-файл и открыть его в браузере, то результаты будут выглядеть следующим образом:
Izzy Siamese 6 yes no Izz138bod Colin Wilcox
Веб-браузер проигнорирует теги XML и отобразит только данные.
Снимки экрана
Все методы, перечисленные в предыдущем разделе, приводят к созданию пригодных для использования блоков кода:
- Вы можете копировать их.
- Они индексируются поисковыми механизмами.
- Они доступны для средств чтения с экрана.
Это лишь несколько из причин, по которым снимки экрана IDE не рекомендуются в качестве метода включения кода в статью. Используйте снимки экрана IDE для кода только в том случае, если вы показываете что-то о самой среде IDE, например IntelliSense. Не используйте снимки экрана, только чтобы показать цвета и выделение.
Ссылки на фрагмент кода в репозитории
- Находясь в Visual Studio Code, нажмите клавиши ALT+M или OPTION+M и выберите "Фрагмент кода".
- Вам будет предложено выполнить поиск по всему содержимому, в какой-то области или по различным репозиториям. Для локального поиска выберите полный поиск.
- Введите условие поиска и найдите нужный файл. Найдя файл, выберите его.
- Затем выберите, какие строки кода нужно включить в фрагмент, используя следующие параметры: ИД, Диапазон или Никакие.
- В зависимости от выбора на шаге 4 предоставьте необходимые значения.
Отображение всего файла кода:
Отображение части файла кода путем указания номера строк:
Отображение части файла кода путем указания имени фрагмента кода:
В следующих разделах описаны эти примеры:
Дополнительные сведения см. в разделе Ссылки на синтаксис фрагментов кода далее в этой статье.
Именованный фрагмент кода
Используйте для имени только буквы и символы подчеркивания.
Именованные фрагменты кода могут быть вложенными, как показано в следующем примере:
При отображении фрагмента Method кода теги Line не включаются в отображаемые выходные данные.
По возможности ссылайтесь на именованный раздел, а не указывайте номера строк. Ссылки на номера строк являются ненадежными, так как файлы кода неизбежно изменяются с помощью способов, которые изменяют номера строк. Вы не обязательно получите уведомления об этих изменениях. В статье в конечном итоге будут отображаться неправильные строки, и вы даже не будете об этом знать.
Дальнейшие действия
Сведения о форматировании текста для типов содержимого, отличных от кода, см. в разделе Рекомендации по форматированию текста.
В предыдущей части мы затронули азы программирования, где рассказали о машинном языке, преобразователях, языках программирования и работе с CLI. Двигаемся дальше.
Исходным кодом называется основной файл вроде Microsoft (.doc), но немного другой. Это текстовый файл, написанный с помощью простых редакторов, таких как Windows Блокнот. В предыдущем разделе мы перечислили, что нужно, чтобы интерпретаторы или компиляторы конвертировали исходный код в двоичный. Первый должен быть сохранен в файле, что передается для ввода в переводчик (преобразователь).
В зависимости от выбранного языка, есть назначенные расширения для сохранения файла: Python – .py. Java – .java. PHP – .php, PERL – .pl и т. д.
Когда вы закончите писать код, запустите его через переводчик. Рассмотрим в качестве примера запуск кода на языке Python с использованием команды python.
Создание ссылок
Ссылка на справочную документацию может оказаться более полезной, чем формат кода в некоторых контекстах. Если используется ссылка, не применяйте формат кода к тексту ссылки. Стилизация ссылки как кода может скрыть тот факт, что текст является ссылкой.
Если вы используете ссылку и ссылаетесь на тот же элемент позже в том же контексте, сделайте последующие экземпляры форматом кода, а не ссылками.
Поддерживаемые языки
Пакет Docs Authoring Pack содержит функцию, обеспечивающую завершение операторов и проверку доступных идентификаторов языков для блоков границ кода.
Сложные типы данных
Указанные выше типы известны как элементарные, первичные или базовые. Мы можем создавать более сложные типы данных из приведенных базовых.
Массив (Array) – это простейшая форма сложного типа. Строка (String) – это массив символов. Мы не можем обойтись без этих данных и часто используем их при написании кода.
Комбинация символов – это строка. Чтобы использовать аналогию, строка для компьютера означает, что слово принадлежит человеку. Слово «термометр» состоит из 9 символов – мы просто называем это строкой символов. Обработка строк – это обширная тема, которая должна изучаться каждым начинающим программистом.
Сложные типы данных поставляются с большинством языков программирования, которые используются. Есть и другие, такие как системы классов. Это явление также известно как объектно-ориентированное программирование (ООП).
Правильно сформированные данные
Правила создания правильно сформированного XML-файла знать необязательно (хотя понять их нетрудно), но следует помнить, что использовать в других приложениях и системах можно лишь правильно сформированные XML-данные. Если XML-файл не открывается, то он, вероятно, неправильно сформирован.
XML не зависит от платформы, и это значит, что любая программа, созданная для использования XML, может читать и обрабатывать XML-данные независимо от оборудования или операционной системы. Например, при применении правильных тегов XML можно использовать программу на настольном компьютере для открытия и обработки данных, полученных с мейнфрейма. И, независимо от того, кто создал XML-данные, с ними данными можно работать в различных приложениях Office. Благодаря своей совместимости XML стал одной из самых популярных технологий обмена данными между базами данных и пользовательскими компьютерами.
В дополнение к правильно сформированным данным с тегами XML-системы обычно используют два дополнительных компонента: схемы и преобразования. В следующих разделах описывается, как они работают.
Пометки, разметка и теги
Чтобы понять XML, полезно понимать идею пометки данных. Люди создавали документы на протяжении многих лет и на протяжении всего времени они их помечали. Например, преподаватели могут постоянно пометить документы учащихся. Учащиеся могут перемещать абзацы, уточнять предложения, исправлять опечатки и так далее. Пометка документа определяет структуру, смысл и внешний вид сведений в документе. Если вы когда-либо использовали функцию "Отслеживание изменений" в Microsoft Office Word, то использовали компьютеризированную форму пометки.
В мире информационных технологий термин "пометка" превратился в термин "разметка". При разметке используются коды, называемые тегами (или иногда токенами), для определения структуры, визуального оформления и — в случае XML — смысла данных.
Текст этой статьи в формате HTML является хорошим примером применения компьютерной разметки. Если в Microsoft Internet Explorer щелкнуть эту страницу правой кнопкой мыши и выбрать команду Просмотр HTML-кода, вы увидите читаемый текст и теги HTML, например
и . В HTML- и XML-документах теги легко распознать, поскольку они заключены в угловые скобки. В исходном тексте этой статьи теги HTML выполняют множество функций, например определяют начало и конец каждого абзаца (
.
) и местоположение рисунков.Литералы
В каждом исходном коде существуют типы данных, которые используются повсюду и изменяются только в том случае, если их отредактировали. Это литералы, которые не следует путать с переменными или константами. Ни один исходный код не обходится без них. Литералы могут быть строками, числами, десятичными знаками или любыми другими типами данных.
В приведенном выше фрагменте слово «Hippo» является строковым литералом. Это всегда будет «Hippo», пока вы не отредактируете исходный код. Когда вы научитесь кодить, узнаете, как управлять литералами таким образом, чтобы оставлять неизменной большую часть кода.
Викторина
Определите элементы, которые мы изучили, в приведенном ниже фрагменте кода Java:
Кажется довольно очевидным, но код пишется не только для компьютеров: он пишется и для людей. Упущение этого факта может обернуться дальнейшими проблемами. Рассказываем, что такое грамотное программирование и как писать качественный код.
Друг моего отца рассказал мне о том, как однажды он наткнулся на действительно ужасный код на работе. Код был просто кошмарным: « плохо написанный, плохо прокомментированный » , – рассказал Джоэл Франушич, инженер по решениям компании Okta, в интервью The New Stack по электронной почте. Он был так взбешен, что решил выяснить, кто же написал этот код, чтобы потом высказать ему все, что он думает.
Но оказалось, что это был его код.
Эта ситуация точно показывает распространенный, но мучительный для программистов опыт: разобраться в коде, независимо от того, чья эта работа – его собственная или постороннего человека. Существует ряд разнообразных способов решения этой проблемы, но есть особенно эффективный, хотя его часто игнорируют — грамотное программирование.
Настройка доступа к репозиторию
Если файл записной книжки, на который требуется сослаться, находится в другом репозитории, нужно настроить репозиторий кода в качестве зависимого репозитория.
Анатомия типичного кода
Теперь мы рассмотрим содержимое типичного файла исходного кода. Ниже приведены регулярные компоненты.
Фрагменты кода в записной книжке Jupyter
Вы можете сослаться на ячейку в записной книжке Jupyter в виде фрагмента кода. Чтобы сослаться на ячейку, сделайте следующее.
- Добавьте метаданные ячеек, на которые вы хотите сослаться, в записную книжку.
- Настройте доступ к репозиторию.
- Используйте синтаксис фрагмента кода записной книжки Jupyter в файле Markdown.
Ключевые слова
Короткие человекочитаемые слова, обычно называемые ключевыми. Они свойственны изучаемому вами языку и они особенны. Их просто нужно знать. Вот небольшой набор ключевых слов, часто используемых в Python.
Явное определение неправильного кода
В некоторых сценариях рекомендуется указывать шаблоны кода, которые следует избегать, например:
- Код, который вызывает ошибку компилятора при попытке выполнения.
- Код, который будет компилироваться правильно, но его рекомендуется выполнять.
Для таких сценариев:
Укажите на ошибку как в комментариях к коду, так и в тексте статьи.
Рассмотрите возможность комментирования кода, если предполагается ошибка компилятора.
Закомментированный код не нарушит работу системы непрерывной интеграции (CI), если в репозитории со статьей он есть сейчас или будет реализован в будущем.
Грамотное программирование на сегодняшний день
Рэмси стал меньше работать над грамотным программированием в 90-х годах. Он прекратил вносить свой вклад в экосистему инструментов и идей. Во многом это было связано с его работой в качестве исследователя; он сконцентрировался на новых проблемах.
Тем не менее, в последнее время его влияние можно заметить в таких различных инструментах, как Jupyter Notebooks и JS-Doc, инструмент разметки для аннотирования кода JavaScript. Язык Haskell также предоставляет способ грамотного программирования, с которым впервые и столкнулся Франушич.
Стоит отметить, защитники программирования могут не согласиться с тем, что эти инструменты выполняют подход грамотного программирования. Они считают, что эти инструментам не хватает контроля над отношениями между кодом и текстом, необходимого для того, чтобы действительно соответствовать оригинальному видению Кнута.
Но невозможно не признать, что целый ряд современных практик извлекают пользу из идей, над которыми трудились Кнут и Рэмси в восьмидесятых и девяностых годах.
У Франушича есть своя личная история, которая может подтвердить его ценность в относительно новой сфере – евангелизме разработчиков и отношениях с ними.
« Мой обычный рабочий процесс, когда я пишу о коде, состоит из следующих шагов:
По его словам, этот способ довольно мучительный, потому что он требует синхронизации двух документов, пока они пишутся. Случается так, что код в статье и код, опубликованный на GitHub, не синхронизируются.
Используя грамотное программирование, он смог решить эту задачу; поскольку код и повествование находятся в одном месте, любые проблемы синхронизации исчезают.
Хотя это немного нестандартный случай, всё же интересно посмотреть, как грамотное программирование обрело новую значимость в контексте мира современного контента для разработчиков и евангелизма разработчиков – то, что было бы совершенно чуждо ориентированным на исследования компьютерным ученым в 80-х годах.
Рэмси говорит, что « грамотное программирование сегодня " скрыто " от студентов на его курсах, однако, он отметил, что много материалов, которые им даются, особенно домашние задания, готовятся, как грамотные программы » . Это потому, что, по его словам, он может гарантировать, что код, который они видят, это код, который на самом деле выполняется.
Параллели между написанием Франушича и обучением Рэмси достойны внимания. Они свидетельствуют о том, что грамотное программирование может предлагать полезный способ не только упорядочить свои идеи, когда дело доходит до написания кода, но и гарантировать уверенность в том, что код будет работать у других людей тоже.
Почему грамотное программирование не получило более массового распространения?
Хотя грамотное программирование, похоже, нашло свой путь в мир статистических вычислений, Рэмси рассказал The New Stack, почему этот подход не обязательно должен использоваться повсюду.
Одна из вещей, которые мы узнали, состоит в том, что это очень дорого. И поэтому вы тратите время, стараясь понять, какие ситуации оправдывают затраты. И одна из них – когда люди создают сравнительно небольшие, сложные ядра, которые будут широко использоваться.
Франушич поддержал эту идею.
Как только я написал грамотную программу, я убедился, что очень трудно реорганизовать или вносить серьезные изменения в эту программу. Поэтому, учитывая это, я начну писать грамотную программу только после того, как буду достаточно уверен, что она максимально готова.
Другими словами, сегодня это просто не подходит для многих инженерных контекстов, особенно для тех, которые подчеркивают скорость и масштаб. Значит ли это, что сегодня практически нечему научить тех, кто пишет код за пределами статистического и численного программирования?
Пунктуация/Символы
В большинстве написанных программ вы найдете различные знаки препинания в зависимости от выбранного языка программирования. Например, в Java используется больше знаков препинания, чем в Python.
Основные знаки включают в себя запятую (,), точку с запятой (;), двоеточие (:), фигурные скобки (<>), обычные круглые скобки (()), квадратные скобки ([]), кавычки ("" или ''), вертикальную черту (|), слэш (\), точку (.), знак вопроса (?), карет (^) и процент (%).
Справочник по синтаксису фрагмента кода записной книжки Jupyter
После добавления в записную книжку необходимых метаданных создайте ссылку на нее в файле Markdown. Используйте имя , добавленное в записную книжку, и путь , настроенный в качестве зависимого репозитория.
Этот синтаксис является блоком расширения Markdown. Он должен использоваться в отдельной строке.
Используйте любой из поддерживаемых языков для идентификатора .
Константы
Константы – это значения, которые не изменяются на протяжении всего жизненного цикла программы. Чаще всего в их именах используются заглавные буквы. Некоторые языки поддерживают создание постоянных значений, а некоторые – нет.
Существуют строго типизированные языки программирования, в которых каждая переменная должна быть определенного типа. Выбрав тип один раз, вы больше не сможете его изменить. Java – хороший пример такого ЯП.
Другие же не предоставляют эти функции. Они являются свободно типизированными или динамическими языками программирования. Пример – Python.
Вот как объявить постоянное значение в JavaScript:
Читайте также: