Skip to main content
Применены более корректные юникод символы: тире, многоточие, стрела вправо.
Источник Ссылка
Vadim Ovchinnikov
  • 9.7k
  • 2
  • 19
  • 40

Так как никто не привел никаких существующих соглашений об использовании внутристрочного выделения кода, я решил опубликовать собственное решение. Оно является моим личным мнением и обобщает мой опыт. Надеюсь, что оно окажется полезным.

Для чего следует использовать внутристрочное выделение

Любая строка, которая обрабатывается или генерируется компьютером, обычно должна быть выделена в тексте. На SO есть единственный способ это сделать (применить внутристрочное выделение кода) - поэтому я использую выделение для подсветки таких строк, когда пишу на SO. В документах для личного пользования, я делаю обычно только одно исключение - использую отдельный стиль оформления текста для выделения элементов пользовательского интерфейса (например, "Файл > Открыть...Открыть…").

Когда внутристрочное выделение использовать не стоит

Строки, которые используются в документах, предназначенных для чтения человеком (например: торговые марки, названия пакетов программ, сами программы, библиотеки, технологии, аббревиатуры) - не выделяются как код, для них должен применяться другой стиль. Например HTTP, TCP/IP, HTML, CSS, AJAX, SQL, Linux, C++, .NET, SaaS, Spring Framework, LibreOffice, iPhone, jQuery, GUI.

О строках, которые обрабатываются или генерируются компьютером

  • небольшие фрагменты листингов (например, SELECT * FROM MyTable, this.id =id;)
  • имена классов, методов, блоков, переменных, параметров методов, строковые константы, имена файлов, пути к файлам, расширения файлов, теги HTML, предложения SQL, фрагменты конфигурационных файлов и тому подобное
  • входные данные программ (например, значения, вводимые пользователем)
  • вывод программ (фрагмент вывода на терминал, фрагмент лога)

Двойственные случаи

Имеются некоторые случаи двойственности: "gedit", - это имя популярного редактора текстов, а также команда, которая этот редактор запускает. Как имя программы, это слово НЕ СЛЕДУЕТ выделять, но как команду, интерпретируемую компьютером, следует. Возможно, форматирование следует выбирать в соответствии с контекстом употребления слова.

О других соглашениях о форматировании

В литературе по программированию часто содержится раздел, который объясняет, каким образом в книге используются те или иные стили текста. Эти соглашения являются более подробными, нежели те, что здесь приведены. Например, для пользовательского ввода и вывода программ могут использоваться отдельные стили. Однако, на SO нет таких возможностей оформления, чтобы удовлетворить такие широкие потребности. Кроме того, написание постов с использованием большого количества стилей, может оказаться трудоемким.

Элементы пользовательского интерфейса

Множество книг используют отдельный стиль текста для выделения таких элементов. Напрмер, "Выделите пункт Сохранить Как...Как… в меню Файл." или Щелкните "Файл > Сохранить как...как…" Возможно, в случае SO, элементы интерфейса также стоит выделять при помощи внутристрочного выделения для кода.

Использование кавычек

Нет необходимости помещать фрагменты кода в дополнительные кавычки - они уже и так выделены. Однако, для строковых констант следует сделать исключение и приводить их вместе с разграничителями. Например: "Метод sayHello() возвращает "Hello World!"."

Примеры

Java (тексты примеров взяты из официальной документации http://docs.oracle.com/)

  • Конвертация в строку осуществляется методом toString, который объявлен в Object и наследуется всеми классами Java.
  • Если не указано иное, передача null в качестве аргумента конструктора или метода вызовет выбрасывание исключения NullPointerException.

Так как никто не привел никаких существующих соглашений об использовании внутристрочного выделения кода, я решил опубликовать собственное решение. Оно является моим личным мнением и обобщает мой опыт. Надеюсь, что оно окажется полезным.

Для чего следует использовать внутристрочное выделение

Любая строка, которая обрабатывается или генерируется компьютером, обычно должна быть выделена в тексте. На SO есть единственный способ это сделать (применить внутристрочное выделение кода) - поэтому я использую выделение для подсветки таких строк, когда пишу на SO. В документах для личного пользования, я делаю обычно только одно исключение - использую отдельный стиль оформления текста для выделения элементов пользовательского интерфейса (например, "Файл > Открыть...").

Когда внутристрочное выделение использовать не стоит

Строки, которые используются в документах, предназначенных для чтения человеком (например: торговые марки, названия пакетов программ, сами программы, библиотеки, технологии, аббревиатуры) - не выделяются как код, для них должен применяться другой стиль. Например HTTP, TCP/IP, HTML, CSS, AJAX, SQL, Linux, C++, .NET, SaaS, Spring Framework, LibreOffice, iPhone, jQuery, GUI.

О строках, которые обрабатываются или генерируются компьютером

  • небольшие фрагменты листингов (например, SELECT * FROM MyTable, this.id =id;)
  • имена классов, методов, блоков, переменных, параметров методов, строковые константы, имена файлов, пути к файлам, расширения файлов, теги HTML, предложения SQL, фрагменты конфигурационных файлов и тому подобное
  • входные данные программ (например, значения, вводимые пользователем)
  • вывод программ (фрагмент вывода на терминал, фрагмент лога)

Двойственные случаи

Имеются некоторые случаи двойственности: "gedit", - это имя популярного редактора текстов, а также команда, которая этот редактор запускает. Как имя программы, это слово НЕ СЛЕДУЕТ выделять, но как команду, интерпретируемую компьютером, следует. Возможно, форматирование следует выбирать в соответствии с контекстом употребления слова.

О других соглашениях о форматировании

В литературе по программированию часто содержится раздел, который объясняет, каким образом в книге используются те или иные стили текста. Эти соглашения являются более подробными, нежели те, что здесь приведены. Например, для пользовательского ввода и вывода программ могут использоваться отдельные стили. Однако, на SO нет таких возможностей оформления, чтобы удовлетворить такие широкие потребности. Кроме того, написание постов с использованием большого количества стилей, может оказаться трудоемким.

Элементы пользовательского интерфейса

Множество книг используют отдельный стиль текста для выделения таких элементов. Напрмер, "Выделите пункт Сохранить Как... в меню Файл." или Щелкните "Файл > Сохранить как..." Возможно, в случае SO, элементы интерфейса также стоит выделять при помощи внутристрочного выделения для кода.

Использование кавычек

Нет необходимости помещать фрагменты кода в дополнительные кавычки - они уже и так выделены. Однако, для строковых констант следует сделать исключение и приводить их вместе с разграничителями. Например: "Метод sayHello() возвращает "Hello World!"."

Примеры

Java (тексты примеров взяты из официальной документации http://docs.oracle.com/)

  • Конвертация в строку осуществляется методом toString, который объявлен в Object и наследуется всеми классами Java.
  • Если не указано иное, передача null в качестве аргумента конструктора или метода вызовет выбрасывание исключения NullPointerException.

Так как никто не привел никаких существующих соглашений об использовании внутристрочного выделения кода, я решил опубликовать собственное решение. Оно является моим личным мнением и обобщает мой опыт. Надеюсь, что оно окажется полезным.

Для чего следует использовать внутристрочное выделение

Любая строка, которая обрабатывается или генерируется компьютером, обычно должна быть выделена в тексте. На SO есть единственный способ это сделать (применить внутристрочное выделение кода) поэтому я использую выделение для подсветки таких строк, когда пишу на SO. В документах для личного пользования, я делаю обычно только одно исключение использую отдельный стиль оформления текста для выделения элементов пользовательского интерфейса (например, "Файл Открыть…").

Когда внутристрочное выделение использовать не стоит

Строки, которые используются в документах, предназначенных для чтения человеком (например: торговые марки, названия пакетов программ, сами программы, библиотеки, технологии, аббревиатуры) не выделяются как код, для них должен применяться другой стиль. Например HTTP, TCP/IP, HTML, CSS, AJAX, SQL, Linux, C++, .NET, SaaS, Spring Framework, LibreOffice, iPhone, jQuery, GUI.

О строках, которые обрабатываются или генерируются компьютером

  • небольшие фрагменты листингов (например, SELECT * FROM MyTable, this.id =id;)
  • имена классов, методов, блоков, переменных, параметров методов, строковые константы, имена файлов, пути к файлам, расширения файлов, теги HTML, предложения SQL, фрагменты конфигурационных файлов и тому подобное
  • входные данные программ (например, значения, вводимые пользователем)
  • вывод программ (фрагмент вывода на терминал, фрагмент лога)

Двойственные случаи

Имеются некоторые случаи двойственности: "gedit", это имя популярного редактора текстов, а также команда, которая этот редактор запускает. Как имя программы, это слово НЕ СЛЕДУЕТ выделять, но как команду, интерпретируемую компьютером, следует. Возможно, форматирование следует выбирать в соответствии с контекстом употребления слова.

О других соглашениях о форматировании

В литературе по программированию часто содержится раздел, который объясняет, каким образом в книге используются те или иные стили текста. Эти соглашения являются более подробными, нежели те, что здесь приведены. Например, для пользовательского ввода и вывода программ могут использоваться отдельные стили. Однако, на SO нет таких возможностей оформления, чтобы удовлетворить такие широкие потребности. Кроме того, написание постов с использованием большого количества стилей, может оказаться трудоемким.

Элементы пользовательского интерфейса

Множество книг используют отдельный стиль текста для выделения таких элементов. Напрмер, "Выделите пункт Сохранить Как… в меню Файл." или Щелкните "Файл Сохранить как…" Возможно, в случае SO, элементы интерфейса также стоит выделять при помощи внутристрочного выделения для кода.

Использование кавычек

Нет необходимости помещать фрагменты кода в дополнительные кавычки они уже и так выделены. Однако, для строковых констант следует сделать исключение и приводить их вместе с разграничителями. Например: "Метод sayHello() возвращает "Hello World!"."

Примеры

Java (тексты примеров взяты из официальной документации http://docs.oracle.com/)

  • Конвертация в строку осуществляется методом toString, который объявлен в Object и наследуется всеми классами Java.
  • Если не указано иное, передача null в качестве аргумента конструктора или метода вызовет выбрасывание исключения NullPointerException.
в текст добавлен 1 символ
Источник Ссылка
Nick Volynkin Мод
  • 34.4k
  • 8
  • 79
  • 217

Так как никто не привел никаких существующих соглашений об использовании внутристрочного выделения кода, я решил опубликовать собственное решение. Оно является моим личным мнением и обобщает мой опыт. Надеюсь, что оно окажется полезным.

Для чего следует использовать внутристрочное выделение

Любая строка, которая обрабатывается или генерируется компьютером, обычно должна быть выделена в тексте. На SO есть единственный способ это сделать (применить внутристрочное выделение кода) - поэтому я использую выделение для подсветки таких строк, когда пишу на SO. В документах для личного пользования, я делаю обычно только одно исключение - использую отдельный стиль оформления текста для выделения элементов пользовательского интерфейса (например, "Файл > Открыть...").

Когда внутристрочное выделение использовать не стоит

Строки, которые используются в документах, предназначенных для чтения человеком (например: торговые марки, названия пакетов программ, сами программы, библиотеки, технологии, аббревиатуры) - не выделяются как код, для них должен применяться другой стиль. Например HTTP, TCP/IP, HTML, CSS, AJAX, SQL, Linux, C++, .NET, SaaS, Spring Framework, LibreOffice, iPhone, jQuery, GUI.

О строках, которые обрабатываются или генерируются компьютером

  • небольшие фрагменты листингов (например, SELECT * FROM MyTable, this.id =id;)
  • имена классов, методов, блоков, переменных, параметров методов, строковые константы, имена файлов, пути к файлам, расширения файлов, теги HTML, предложения SQL, фрагменты конфигурационных файлов и тому подобное
  • входные данные программ (например, значения, вводимые пользователем)
  • вывод программ (фрагмент вывода на терминал, фрагмент лога)

Двойственные случаи

Имеются некоторые случаи двойственности: "gedit", - это имя популярного редактора текстов, а также команда, которая этот редактор запускает. Как имя программы, это слово НЕ СЛЕДУЕТ выделять, но как команду, интерпретируемую компьютером, следует. Возможно, форматирование следует выбирать в соответствии с контекстом употребления слова.

О других соглашениях о форматировании

В литературе по программированию часто содержится раздел, который объясняет, каким образом в книге используются те или иные стили текста. Эти соглашения являются более подробными, нежели те, что здесь приведены. Например, для пользовательского ввода и вывода программ могут использоваться отдельные стили. Однако, на SO нет таких возможностей оформления, чтобы удовлетворить такие широкие потребности. Кроме того, написание постов с использованием большого количества стилей, может оказаться трудоемким.

Элементы пользовательского интерфейса

Множество книг используют отдельный стиль текста для выделения таких элементов. Напрмер, "Выделите пункт Сохранить Как... в меню Файл." или Щелкните "Файл > Сохранить как..." Возможно, в случае SO, элементы интерфейса также стоит выделять при помощи внутристрочного выделения для кода.

Использование кавычек

Нет необходимости помещать фрагменты кода в дополнительные кавычки - они уже и так выделены. Однако, для строковых констант следует сделать исключение и приводить их вместе с разграничителями. Например: "Метод sayHello() возвращает "Hello World!"."

Примеры

Java (тексты примеров взяты из официальной документации http://docs.oracle.com/)

  • Конвертация в строку осуществляется методом toString, который объявлен в Object и наследуется всеми классами Java.
  • Если не указано иное, передача null в качестве аргумента конструктора или метода вызовет выбрасывание исключения NullPointerException.

Так как никто не привел никаких существующих соглашений об использовании внутристрочного выделения кода, я решил опубликовать собственное решение. Оно является моим личным мнением и обобщает мой опыт. Надеюсь, что оно окажется полезным.

Для чего следует использовать внутристрочное выделение

Любая строка, которая обрабатывается или генерируется компьютером, обычно должна быть выделена в тексте. На SO есть единственный способ это сделать (применить внутристрочное выделение кода) - поэтому я использую выделение для подсветки таких строк, когда пишу на SO. В документах для личного пользования, я делаю обычно только одно исключение - использую отдельный стиль оформления текста для выделения элементов пользовательского интерфейса (например, "Файл > Открыть...").

Когда внутристрочное выделение использовать не стоит

Строки, которые используются в документах, предназначенных для чтения человеком (например: торговые марки, названия пакетов программ, сами программы, библиотеки, технологии, аббревиатуры) - не выделяются как код, для них должен применяться другой стиль. Например HTTP, TCP/IP, HTML, CSS, AJAX, SQL, Linux, C++, .NET, SaaS, Spring Framework, LibreOffice, iPhone, jQuery, GUI.

О строках, которые обрабатываются или генерируются компьютером

  • небольшие фрагменты листингов (например, SELECT * FROM MyTable, this.id =id;)
  • имена классов, методов, блоков, переменных, параметров методов, строковые константы, имена файлов, пути к файлам, расширения файлов, теги HTML, предложения SQL, фрагменты конфигурационных файлов и тому подобное
  • входные данные программ (например, значения, вводимые пользователем)
  • вывод программ (фрагмент вывода на терминал, фрагмент лога)

Двойственные случаи

Имеются некоторые случаи двойственности: "gedit", - это имя популярного редактора текстов, а также команда, которая этот редактор запускает. Как имя программы, это слово НЕ СЛЕДУЕТ выделять, но как команду, интерпретируемую компьютером, следует. Возможно, форматирование следует выбирать в соответствии с контекстом употребления слова.

О других соглашениях о форматировании

В литературе по программированию часто содержится раздел, который объясняет, каким образом в книге используются те или иные стили текста. Эти соглашения являются более подробными, нежели те, что здесь приведены. Например, для пользовательского ввода и вывода программ могут использоваться отдельные стили. Однако, на SO нет таких возможностей оформления, чтобы удовлетворить такие широкие потребности. Кроме того, написание постов с использованием большого количества стилей, может оказаться трудоемким.

Элементы пользовательского интерфейса

Множество книг используют отдельный стиль текста для выделения таких элементов. Напрмер, "Выделите пункт Сохранить Как... в меню Файл." или Щелкните "Файл > Сохранить как..." Возможно, в случае SO, элементы интерфейса также стоит выделять при помощи внутристрочного выделения для кода.

Использование кавычек

Нет необходимости помещать фрагменты кода в дополнительные кавычки - они уже и так выделены. Однако, для строковых констант следует сделать исключение и приводить их вместе с разграничителями. Например: "Метод sayHello() возвращает "Hello World!"."

Примеры

Java (тексты примеров взяты из официальной документации http://docs.oracle.com/)

  • Конвертация в строку осуществляется методом toString, который объявлен в Object и наследуется всеми классами Java.
  • Если не указано иное, передача null в качестве аргумента конструктора или метода вызовет выбрасывание исключения NullPointerException

Так как никто не привел никаких существующих соглашений об использовании внутристрочного выделения кода, я решил опубликовать собственное решение. Оно является моим личным мнением и обобщает мой опыт. Надеюсь, что оно окажется полезным.

Для чего следует использовать внутристрочное выделение

Любая строка, которая обрабатывается или генерируется компьютером, обычно должна быть выделена в тексте. На SO есть единственный способ это сделать (применить внутристрочное выделение кода) - поэтому я использую выделение для подсветки таких строк, когда пишу на SO. В документах для личного пользования, я делаю обычно только одно исключение - использую отдельный стиль оформления текста для выделения элементов пользовательского интерфейса (например, "Файл > Открыть...").

Когда внутристрочное выделение использовать не стоит

Строки, которые используются в документах, предназначенных для чтения человеком (например: торговые марки, названия пакетов программ, сами программы, библиотеки, технологии, аббревиатуры) - не выделяются как код, для них должен применяться другой стиль. Например HTTP, TCP/IP, HTML, CSS, AJAX, SQL, Linux, C++, .NET, SaaS, Spring Framework, LibreOffice, iPhone, jQuery, GUI.

О строках, которые обрабатываются или генерируются компьютером

  • небольшие фрагменты листингов (например, SELECT * FROM MyTable, this.id =id;)
  • имена классов, методов, блоков, переменных, параметров методов, строковые константы, имена файлов, пути к файлам, расширения файлов, теги HTML, предложения SQL, фрагменты конфигурационных файлов и тому подобное
  • входные данные программ (например, значения, вводимые пользователем)
  • вывод программ (фрагмент вывода на терминал, фрагмент лога)

Двойственные случаи

Имеются некоторые случаи двойственности: "gedit", - это имя популярного редактора текстов, а также команда, которая этот редактор запускает. Как имя программы, это слово НЕ СЛЕДУЕТ выделять, но как команду, интерпретируемую компьютером, следует. Возможно, форматирование следует выбирать в соответствии с контекстом употребления слова.

О других соглашениях о форматировании

В литературе по программированию часто содержится раздел, который объясняет, каким образом в книге используются те или иные стили текста. Эти соглашения являются более подробными, нежели те, что здесь приведены. Например, для пользовательского ввода и вывода программ могут использоваться отдельные стили. Однако, на SO нет таких возможностей оформления, чтобы удовлетворить такие широкие потребности. Кроме того, написание постов с использованием большого количества стилей, может оказаться трудоемким.

Элементы пользовательского интерфейса

Множество книг используют отдельный стиль текста для выделения таких элементов. Напрмер, "Выделите пункт Сохранить Как... в меню Файл." или Щелкните "Файл > Сохранить как..." Возможно, в случае SO, элементы интерфейса также стоит выделять при помощи внутристрочного выделения для кода.

Использование кавычек

Нет необходимости помещать фрагменты кода в дополнительные кавычки - они уже и так выделены. Однако, для строковых констант следует сделать исключение и приводить их вместе с разграничителями. Например: "Метод sayHello() возвращает "Hello World!"."

Примеры

Java (тексты примеров взяты из официальной документации http://docs.oracle.com/)

  • Конвертация в строку осуществляется методом toString, который объявлен в Object и наследуется всеми классами Java.
  • Если не указано иное, передача null в качестве аргумента конструктора или метода вызовет выбрасывание исключения NullPointerException.
из текста удален 1 символ
Источник Ссылка
gbg
  • 22.3k
  • 11
  • 14

Так как никто не привел никаких существующих соглашений об использовании внутристрочного выделения кода, я решил опубликовать собственное решение. Оно является моим личным мнением и обобщает мой опыт. Надеюсь, что оно окажется полезным.

Для чего следует использовать внутристрочное выделение

Любая строка, которая обрабатывается или генерируется компьютером, обычно должна быть выделена в тексте. На SO есть единственный способ это сделать (применить внутристрочное выделение кода) - поэтому я использую выделение для подсветки таких строк, когда пишу на SO. В документах для личного пользования, я делаю обычно только одно исключение - использую отдельный стиль оформления текста для выделения элементов пользовательского интерфейса (например, "Файл > Открыть...").

Когда внутристрочное выделение использовать не стоит

Строки, которые используются в документах, предназначенных для чтения человеком (например: торговые марки, названия пакетов программ, сами программы, библиотеки, технологии, аббревиатуры) - не выделяются как код, для них должен применяться другой стиль. Например HTTP, TCP/IP, HTML, CSS, AJAX, SQL, Linux, C++, .NET, SaaS, Spring Framework, LibreOffice, iPhone, jQuery, GUI.

О строках, которые обрабатываются или генерируются компьютером

  • небольшие фрагменты листингов (например, SELECT * FROM MyTable, this.id =id;)
  • имена классов, методов, блоков, переменных, параметров методов, строковые константы, имена файлов, пути к файлам, расширения файлов, теги HTML, предложения SQL, фрагменты конфигурационных файлов и тому подобное
  • входные данные программ (например, значения, вводимые пользователем)
  • вывод программ (фрагмент вывода на терминал, фрагмент лога)

Двойственные случаи

Имеются некоторые случаи двойственности: "gedit", - это имя популярного редактора текстов, а также команда, которая этот редактор запускает. Как имя программы, это слово НЕ СЛЕДУЕТ выделять, но как команду, интерпретируемую компьютером, следует. Возможно, форматирование следует выбирать в соответствии с контекстом употребления слова.

О других соглашениях о форматировании

В литературе по программированию часто содержится раздел, который объясняет, каким образом в книге используются те или иные стили текста. Эти соглашения являются более подробными, нежели те, что здесь приведены. Например, для пользовательского ввода и вывода программ могут использоваться отдельные стили. Однако, на SO нет таких возможностей оформления, чтобы удовлетворить такие широкие потребности. Кроме того, написание постов с использованием большого количества стилей, может оказаться трудоемким.

Элементы пользовательского интерфейса

Множество книг используют отдельный стиль текста для выделения таких элементов. Напрмер, "Выделите пункт Сохранить Как... в меню Файл." или Щелкните "Файл > Сохранить как..." Возможно, в случае SO, элементы интерфейса также стоит выделять при помощи внутристрочного выделения для кода.

Использование кавычек

Нет необходимости помещать фрагменты кода в дополнительные кавычки - они уже и так выделены. Однако, для строковых констант следует сделать исключение и приводить их вместе с разграничителями. Например: "Метод sayHello()" возвращает "Hello World!"."

Примеры

Java (тексты примеров взяты из официальной документации http://docs.oracle.com/)

  • Конвертация в строку осуществляется методом toString, который объявлен в Object и наследуется всеми классами Java.
  • Если не указано иное, передача null в качестве аргумента конструктора или метода вызовет выбрасывание исключения NullPointerException

Так как никто не привел никаких существующих соглашений об использовании внутристрочного выделения кода, я решил опубликовать собственное решение. Оно является моим личным мнением и обобщает мой опыт. Надеюсь, что оно окажется полезным.

Для чего следует использовать внутристрочное выделение

Любая строка, которая обрабатывается или генерируется компьютером, обычно должна быть выделена в тексте. На SO есть единственный способ это сделать (применить внутристрочное выделение кода) - поэтому я использую выделение для подсветки таких строк, когда пишу на SO. В документах для личного пользования, я делаю обычно только одно исключение - использую отдельный стиль оформления текста для выделения элементов пользовательского интерфейса (например, "Файл > Открыть...").

Когда внутристрочное выделение использовать не стоит

Строки, которые используются в документах, предназначенных для чтения человеком (например: торговые марки, названия пакетов программ, сами программы, библиотеки, технологии, аббревиатуры) - не выделяются как код, для них должен применяться другой стиль. Например HTTP, TCP/IP, HTML, CSS, AJAX, SQL, Linux, C++, .NET, SaaS, Spring Framework, LibreOffice, iPhone, jQuery, GUI.

О строках, которые обрабатываются или генерируются компьютером

  • небольшие фрагменты листингов (например, SELECT * FROM MyTable, this.id =id;)
  • имена классов, методов, блоков, переменных, параметров методов, строковые константы, имена файлов, пути к файлам, расширения файлов, теги HTML, предложения SQL, фрагменты конфигурационных файлов и тому подобное
  • входные данные программ (например, значения, вводимые пользователем)
  • вывод программ (фрагмент вывода на терминал, фрагмент лога)

Двойственные случаи

Имеются некоторые случаи двойственности: "gedit", - это имя популярного редактора текстов, а также команда, которая этот редактор запускает. Как имя программы, это слово НЕ СЛЕДУЕТ выделять, но как команду, интерпретируемую компьютером, следует. Возможно, форматирование следует выбирать в соответствии с контекстом употребления слова.

О других соглашениях о форматировании

В литературе по программированию часто содержится раздел, который объясняет, каким образом в книге используются те или иные стили текста. Эти соглашения являются более подробными, нежели те, что здесь приведены. Например, для пользовательского ввода и вывода программ могут использоваться отдельные стили. Однако, на SO нет таких возможностей оформления, чтобы удовлетворить такие широкие потребности. Кроме того, написание постов с использованием большого количества стилей, может оказаться трудоемким.

Элементы пользовательского интерфейса

Множество книг используют отдельный стиль текста для выделения таких элементов. Напрмер, "Выделите пункт Сохранить Как... в меню Файл." или Щелкните "Файл > Сохранить как..." Возможно, в случае SO, элементы интерфейса также стоит выделять при помощи внутристрочного выделения для кода.

Использование кавычек

Нет необходимости помещать фрагменты кода в дополнительные кавычки - они уже и так выделены. Однако, для строковых констант следует сделать исключение и приводить их вместе с разграничителями. Например: "Метод sayHello()" возвращает "Hello World!"."

Примеры

Java (тексты примеров взяты из официальной документации http://docs.oracle.com/)

  • Конвертация в строку осуществляется методом toString, который объявлен в Object и наследуется всеми классами Java.
  • Если не указано иное, передача null в качестве аргумента конструктора или метода вызовет выбрасывание исключения NullPointerException

Так как никто не привел никаких существующих соглашений об использовании внутристрочного выделения кода, я решил опубликовать собственное решение. Оно является моим личным мнением и обобщает мой опыт. Надеюсь, что оно окажется полезным.

Для чего следует использовать внутристрочное выделение

Любая строка, которая обрабатывается или генерируется компьютером, обычно должна быть выделена в тексте. На SO есть единственный способ это сделать (применить внутристрочное выделение кода) - поэтому я использую выделение для подсветки таких строк, когда пишу на SO. В документах для личного пользования, я делаю обычно только одно исключение - использую отдельный стиль оформления текста для выделения элементов пользовательского интерфейса (например, "Файл > Открыть...").

Когда внутристрочное выделение использовать не стоит

Строки, которые используются в документах, предназначенных для чтения человеком (например: торговые марки, названия пакетов программ, сами программы, библиотеки, технологии, аббревиатуры) - не выделяются как код, для них должен применяться другой стиль. Например HTTP, TCP/IP, HTML, CSS, AJAX, SQL, Linux, C++, .NET, SaaS, Spring Framework, LibreOffice, iPhone, jQuery, GUI.

О строках, которые обрабатываются или генерируются компьютером

  • небольшие фрагменты листингов (например, SELECT * FROM MyTable, this.id =id;)
  • имена классов, методов, блоков, переменных, параметров методов, строковые константы, имена файлов, пути к файлам, расширения файлов, теги HTML, предложения SQL, фрагменты конфигурационных файлов и тому подобное
  • входные данные программ (например, значения, вводимые пользователем)
  • вывод программ (фрагмент вывода на терминал, фрагмент лога)

Двойственные случаи

Имеются некоторые случаи двойственности: "gedit", - это имя популярного редактора текстов, а также команда, которая этот редактор запускает. Как имя программы, это слово НЕ СЛЕДУЕТ выделять, но как команду, интерпретируемую компьютером, следует. Возможно, форматирование следует выбирать в соответствии с контекстом употребления слова.

О других соглашениях о форматировании

В литературе по программированию часто содержится раздел, который объясняет, каким образом в книге используются те или иные стили текста. Эти соглашения являются более подробными, нежели те, что здесь приведены. Например, для пользовательского ввода и вывода программ могут использоваться отдельные стили. Однако, на SO нет таких возможностей оформления, чтобы удовлетворить такие широкие потребности. Кроме того, написание постов с использованием большого количества стилей, может оказаться трудоемким.

Элементы пользовательского интерфейса

Множество книг используют отдельный стиль текста для выделения таких элементов. Напрмер, "Выделите пункт Сохранить Как... в меню Файл." или Щелкните "Файл > Сохранить как..." Возможно, в случае SO, элементы интерфейса также стоит выделять при помощи внутристрочного выделения для кода.

Использование кавычек

Нет необходимости помещать фрагменты кода в дополнительные кавычки - они уже и так выделены. Однако, для строковых констант следует сделать исключение и приводить их вместе с разграничителями. Например: "Метод sayHello() возвращает "Hello World!"."

Примеры

Java (тексты примеров взяты из официальной документации http://docs.oracle.com/)

  • Конвертация в строку осуществляется методом toString, который объявлен в Object и наследуется всеми классами Java.
  • Если не указано иное, передача null в качестве аргумента конструктора или метода вызовет выбрасывание исключения NullPointerException
в текст добавлен 1 символ
Источник Ссылка
Nick Volynkin Мод
  • 34.4k
  • 8
  • 79
  • 217
Загрузка
Опечатка в оформлении
Источник Ссылка
Загрузка
Источник Ссылка
gbg
  • 22.3k
  • 11
  • 14
Загрузка