Начинаете предложение с имени функции? [закрыто]

42

Иногда, набирая что-то, относящееся к регистрозависимому языку программирования, я заканчиваю тем, что начинаю предложение с имени функции. Теперь правила английского языка гласят, что первое слово в предложении должно быть написано с большой буквы; хотя имя функции строчное Если вам интересно, что я могу сказать, что в результате первое слово будет именем функции, возьмите этот пример:

Ваша хреновая реализация сломана. fread должен вернуть количество прочитанных байтов.

Я понимаю, что могу изменить второй экземпляр fread на It, но я хочу знать лучший способ справиться с этим, кроме переписывания предложения. Должен ли я использовать заглавные буквы имени функции? Единственный способ, которым я хотел бы услышать «переписать предложение» в качестве ответа, - это если предложение, начинающееся с имени функции, нарушает какое-то английское правило, о котором я не знаю. Изменить: я действительно благодарю всех за эти ответы. Они изменили и улучшили мое понимание проблемы. Я многому научился из этого. Я очень удивлен, что я не подумал об этих простых, но хороших решениях.

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

functions

— user3462295
источник

1

@gnat Я не спрашиваю, как назвать что-то, я спрашиваю, как начать предложение с имени функции.

— user3462295

13

В математике существует сходное соглашение: не следует начинать предложение с имени переменной или формулы. И это несмотря на то, что у нас есть типографское соглашение о том, что переменные и формулы отображаются курсивом, чтобы отделить их от текста. Можно было бы не писать «Пусть x будет степенью 2. x положительно, так что ...» Обычное решение - перефразировать или добавить какое-нибудь слово-наполнитель: «Теперь x положительно» или «У нас есть x положительно» или что-то в этом роде.

— Нейт Элдридж

9

Идентификатор из языка программирования должен рассматриваться как иностранное слово и не должен подчиняться тем же правилам английского языка.

— Rufflewind

1

Есть несколько удивительно активных программистов на английском. SE ( tchrist ... не так уж много, Эрик Липперт ) - но это зависит от типа ответа, который вы хотите. Мы пишем это как программисты на сайте, ориентированном на программистов. Если вас больше интересуют формальности технического письма, руководства по журналам и правильная структура предложений на английском языке, вы можете пересмотреть свою целевую аудиторию экспертов.

2

Этот вопрос кажется не по теме, потому что это английский язык и использование, и у нас есть целый сайт StackExchange для этого. Действительно, есть по крайней мере четыре подобные вопросы там . Кроме того, разные ответы могут быть одинаково действительны в зависимости от того, где написано письмо, и т. Д.

— Калеб

87

В типографии это обычно обрабатывается с использованием другого рендеринга, независимо от того, является ли это началом предложения, чтобы показать, что то, что бросается в глаза, это не просто слово в предложении, а особый объект.

Ваша freadреализация не работает. freadНеобходимо вернуть, сколько байтов было прочитано.

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

В простом текстовом мире (как отмечалось несколькими в комментариях и других ответах) добавление скобок к именам функций немного помогает, но поскольку нам также нужно ссылаться на сущности, которые не заключают в скобки, это имеет только ограниченное значение. В целом, если не принимать соглашение об окружении текста специальными символами, такими как квадратные скобки и звездочки, в мире простого текста нет другого выбора, кроме как обойти проблему путем перестройки предложения.

— Reg Edit
источник

Да, я понимаю вашу точку зрения, она все еще неуклюже, но менее неловко. Однако я понимаю, что чувства не всегда соответствуют правилам грамматики и письма. Я не уверен, есть ли лучший способ справиться с этим, поэтому я приму ваш ответ, если кто-то не придумает что-то лучшее.

— user3462295

25

Я часто просто выделяю курсивом для таких вещей - вы всегда должны поддерживать регистр чувствительных к регистру терминов, независимо от того, где они находятся в предложении, IMO. freadэто не слово; это символ, представляющий сущность. Это не подлежит грамматике.

— Муравей P

4

И ... что вы делаете, если вам приходится иметь дело с простым текстом? Как в небольшом .txt файле справки или в текстовом электронном письме? Я предлагаю также включить этот сценарий в ваш ответ.

— Эллеседил

2

@Ellesedil В этом случае я обычно добавляю суффикс ()или (...)обозначаю, что это функция. Но это не всегда работает, особенно при работе с переменными и тому подобным. Затем я оборачиваю имя `(галочкой), чтобы обозначить его код.

— Коул Джонсон

4

@Ellesedil Я привык использовать синтаксис уценки для обозначения элементов кода, даже в контексте простого текста, такого как комментарии. Это единственный раз, когда мне нужно было использовать символ обратного тона при написании простым английским языком.

— Кин

53

Если существует абсолютное требование начинать каждое предложение с заглавной буквы, просто замените его freadна « freadФункция», где бы оно ни начиналось.

— х-код
источник

21

Если у вас нет типографских средств для различения (как в другом ответе), и, возможно, даже если у вас есть, это может быть полезно, чтобы указать, что вы говорите о функции, используя parens:

Ваша реализация fread () не работает. Функция fread () должна вернуть количество прочитанных байтов.

Это помогает «объяснить», почему оно не пишется с заглавной буквы в начале второго предложения, а также помогает (в первом предложении) понять, почему собственное существительное (имя функции) там тоже не пишется с заглавной буквы . Поскольку (как собственно существительное) это, возможно, должно было быть.

(«возможно», потому что мы можем утверждать, является ли fread () родовым существительным или собственным).

В целом, использование паренов помогает мозгу читателя понять, почему появляются странные слова и чем они являются.

— GreenAsJade
источник

5

Использование скобок также помогает уменьшить избыточность текста. Вместо «функция fread» вы можете сказать просто «fread ()». И это также полезно, если у вас есть своего рода подсветка, чтобы подчеркнуть разницу между такими вещами, как имена переменных и функции.

— Paul92

3

Я думаю, что скобки только добавляют больше путаницы. fread()может быть оператором вызова. Или это может быть ссылка на перегруженную функцию без параметров.

— kapex

4

@kapep Обычно в документах, относящихся к коду, func_name()читается как «функция по имени func_name», независимо от того, имеет ли сама функция какие-либо параметры.

— Эрик Финн

3

@EricFinn По моему опыту, это обычно относится к функциям без параметров, но это зависит от языка и его соглашений. Например, в официальных руководствах по комментариям Java не рекомендуется использовать круглые скобки: «При ссылке на [конкретную форму метода] используйте круглые скобки и типы аргументов. [...] Однако, если вы ссылаетесь на обе формы метода, пропустите круглые скобки. Вводить в заблуждение пустые скобки вводит в заблуждение, потому что это подразумевает особую форму метода " oracle.com/technetwork/java/javase/documentation/…

— kapex

3

Хотя добавление визуальной подсказки, безусловно, является хорошей идеей (лучше всего это выделенный шрифт или иное выделение), я согласен с Капепом в том, что добавление пустых паренсов - это действительно проблематичный выбор, потому что в каждом языке, который я знаю, f()что-то отличается от f. Почему бы не окружить имя каким-нибудь подходящим символом, например, «fread» в стиле markdown (это то, что я обычно делаю в сообщениях коммитов VCS)? Или просто (фред). Конечно, любая такая вещь должна выполняться последовательно, а не только для функций в начале предложения.

— оставил около

10

Вы можете начать предложение с описания:

Функция fread[…]

Метод fread[…]

Недвижимость breadColor[…]

— Давид Сергей
источник

@ Зак: Президент Обама.

— Марк ван Леувен

@MarcvanLeeuwen Названия - это особый случай. (Также «Королева Елизавета», «Мистер Роджерс».) У меня нет правильного анализа на макушке, но интуитивно я думаю, что они считаются частью имени, а не тегом категории.

— zwol

8

Вы можете сравнить это со встроенной математикой в публикациях. Вы очень редко будете видеть предложения, начинающиеся с переменной или другой встроенной математики.

Таким образом, я заключаю, что вы должны избегать имен функций в начале предложения.

Может быть, этот вопрос содержит более подробную информацию: можно ли начинать предложение с греческой буквы (переменной)? ,

— Lukas
источник

3

+1. В « Математическом доказательстве» (Chartrand et al., 2000), глава 0 которого представляет собой полезный совет для математического письма, самое первое правило в разделе « Использование символов» - «Никогда не начинайте предложение с символа». (Пример - это предложение, начинающееся с уравнения; авторы предлагают предварительно добавить его к «Уравнению ___».) Хотя не все математические рекомендации по написанию обязательно относятся к написанию об исходном коде, я думаю, что это один бит, который делает.

— Руах

1

Я не уверен, что согласен с аналогией. Символы, такие как $ x $, являются переходными к уравнению, поэтому странно ссылаться на них, как будто они имеют глобальное значение. Если бы символ, такой как $ \ pi $, начинал предложение, я бы чувствовал себя комфортно как читатель.

— Джечлин

1

@djechlin Я не уверен, что начало предложения с символа подразумевает, что оно имеет глобальное значение или фактически имеет какое-либо отношение к этому.

— Кайл Стрэнд,

@KyleStrand было бы хорошо знать, почему вы никогда не должны начинать предложение с символа. "$ \ pi $ is ..." v. "Математическая константа $ \ pi $ is ..." - вы выбираете.

— Джечлин

1

@djechlin: Одна из причин в том, что если предыдущее предложение заканчивается математикой, математика в начале следующего предложения может выглядеть как часть той же формулы с точкой между ними. (Это еще большая проблема с запятыми.) Другая проблема заключается в том, что, поскольку имена переменных обычно строчные, глаз читателя теряет визуальный смысл поиска заглавной буквы, чтобы найти начало следующего предложения.

— Нейт Элдридж

3

Справочная страница Linux для fread (3) , на которую ссылались другие, является отличным примером четырех распространенных решений.

Начните свое предложение с «Функция foo» или «Функция foo». Msgstr "Функция fread должна вернуться ..." .
Пометьте имя функции дополнительными символами в соответствии с соглашением, используемым вашим сообществом языков программирования. В случае C, пустая пара круглых скобок, поэтому «fread () нужно вернуть ...» .
Используйте типографику (жирный шрифт, символы фиксированной ширины или курсив), чтобы выделить имя функции, например: « fread нужно вернуть ...»
В системах, которые используют man, если ваша функция имеет справочную страницу, обратитесь к главе руководства в скобках. Так что "fread (3) нужно вернуть ..."

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

Как вы сказали, вы не можете полагаться на типографику, чтобы выделить название вашей функции. Синтаксис Markdown предназначен для создания удобочитаемой документации даже тогда, когда интерпретатор markdown недоступен, поэтому непременно окружите имя вашей функции парой обратных символов. (Это, я думаю, комбинация вариантов 2 и 3.)

Вариант 2 зависит от языка программирования. Например, документы Ruby и Smalltalk часто предшествуют именам методов экземпляра с помощью хеша, например #fread . Между тем Лисперс может предпочесть, чтобы имя функции было пустым, но поймет, если вы напишите вызов функции скелета, такой как (fread ...) или (fread) . Промойте и повторите для всех языков, которые вы документируете.

— dcorking
источник

Мне нравится твой ответ. Благодаря такому написанию функций функции выглядят лучше.

— user3462295

2

Я собираюсь ответить только за конкретный пример:

Ваша хреновая реализация сломана. fread должен вернуть количество прочитанных байтов.

Просто замените первую точку остановки (точка) точкой с запятой:

Ваша реализация fread не работает; fread должен вернуть количество прочитанных байтов.

— EdHunter
источник

3

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

— Мартин МакКаллион,

Так что использование запятой не всегда работает; но зачем использовать запятую?

— сообщение от

Это не запятая. Это точка с запятой; правильное использование точки с запятой при этом.

— RubberDuck

1

Я бы лично использовал здесь двоеточие вместо точки с запятой (хотя она хорошо читается и с точкой с запятой).

— Марк ван Леувен

0

Я знаю, что на этот вопрос уже дан ответ, и принятый ответ довольно хорош, но я просто хочу кое-что прояснить.

В правильной грамматике английского языка, суть заключается в следующем: иногда именам, имеющим собственное имя, дают имена, которые не начинаются с заглавной буквы, и в большинстве таких случаев они все равно привязаны к тому, что не пишутся с заглавной буквы, как «нормальные» имена капитализируется. В таких случаях, которые, безусловно, включают в себя большинство имен функций на языках С-спуска, вы абсолютно не пишете заглавными буквами даже в начале предложения. На самом деле, это плохая грамматика английского языка и орфография. На самом деле это часть того же принципа, почему правильно называть игровую консоль Sony «PlayStation», а не «Playstation».

Есть и другие случаи, в которых собственное существительное не должно начинаться с заглавной буквы по умолчанию, и все же это может быть (и должно быть) при использовании в начале предложения. Название языка brainfuck является примером этого. Функции на С-спущенных языках нет. myFunc()и MyFunc()это две совершенно разные вещи в подобных языках, и начало предложения со слова «MyFunc ()» будет относиться только к последнему, а не к первому. В VB.NET, однако, это серая область, поскольку эти две функции будут одинаковыми на этом языке, хотя имена функций также сохранят схемы капитализации, заданные пользователем, на том или ином уровне.

Кроме того, несмотря на то, что в этом случае английские правила изложены в камне, они, как правило, становятся немного туманными в таких вещах. Английский не был разработан с такими вещами в виду, поэтому для других вещей, как это, есть место для импровизации.

— Panzercrisis
источник