Початок речення з назвою функції? [зачинено]

Іноді під час введення чого-небудь, що стосується чутливої ​​до регістру мови програмування, я починаю речення з назвою функції. Тепер норми англійської мови стверджують, що перше слово в реченні має бути з великої літери; Хоча назва функції - це малі літери. Якщо вам цікаво, що я можу сказати, це призведе до того, що перше слово буде назвою функції, візьміть цей приклад:

Ваша фрейд-реалізація порушена. fread потребує повернення, скільки байтів було прочитано.

Я розумію, що я міг би змінити другий екземпляр фреда на нього, але я хочу знати найкращий спосіб поводження з цим, крім простого переписування вироку. Чи слід писати великі літери назви функції? Єдиний спосіб, який я хотів би почути як "переписати речення" як відповідь, це якщо початок речення з назвою функції порушує якесь англійське правило, про яке я не знаю. Редагувати: Я дуже дякую всім за ці відповіді. Вони змінили та покращили моє розуміння проблеми. Я з цього навчився зовсім небагато. Я дуже здивований, що не думав про ці прості, але хороші рішення.

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

У типографії це, як правило, обробляється за допомогою різного відображення, будь то початок речення чи ні, щоб вказати, що те, що потрапляє в око, є не просто словом у реченні, а особливою сутністю.

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

Залежно від того, наскільки формальним є документ, він може використовувати той самий підхід. У будь-якому випадку це усуває проблему, яку ви ідентифікуєте, тож, можливо, ви хочете скористатися нею лише з цієї причини.

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

Якщо є абсолютна вимога починати кожне речення з великої літери, то просто замініть freadна " freadФункцію", де б воно не почалося реченням.

Якщо у вас немає типографічних засобів для розрізнення (за іншою відповіддю), і, можливо, навіть якщо ви це зробите, це може бути корисно вказати, що ви говорите про функцію, використовуючи паролі:

Ваша реалізація fread () порушена. fread () повинен повернути, скільки байтів було прочитано.

Це допомагає «пояснити» , чому вона не капіталізується на початку другого речення, а також допомагає (в першому реченні) , щоб зрозуміти , чому власна назва (назва функції) НЕ капіталізуються там або . Оскільки (як власне іменник) це, мабуть, мало бути.

("можливо", тому що ми можемо стверджувати, що fread () є родовим іменником чи власним іменником).

Загалом, використання паронів допомагає мозку читача зрозуміти, чому з’являються дивні слова та якими вони є.

Почати речення можна з опису:

Функція fread[…]

Метод fread[…]

Властивість breadColor[…]

Ви можете порівняти це з вбудованою математикою у публікаціях. Ви дуже рідко побачите речення, що починаються зі змінної чи іншої вбудованої математики.

Таким чином, я підсумую, вам слід уникати імен функцій на початку речення.

Можливо, це запитання містить додаткові деталі: Чи добре починати речення з грецької літери (змінної)? .

Сторінка man для Linux для fread (3), з якою пов'язані інші, - чудовий приклад чотирьох загальних рішень.

1. Почніть своє речення з "Функції foo" або "Foo function". "Функція fread потребує повернення ..." .
2. Позначте ім'я функції додатковими символами згідно з умовами, якими користується мовна спільнота мов програмування. У випадку з C порожня пара дужок, тому "fread () потрібно повернути ..." .
3. Використовуйте типографіку (жирним шрифтом, символами фіксованої ширини або курсивом), щоб виділити ім'я функції, як: " fread потребує повернення ..."
4. Про системи, які використовують man, якщо у вашій функції є підручна сторінка, зверніться до розділу керівництва в дужках. Отже, "fread (3) потребує повернення ..."

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

Як ви вже говорили, ви не можете розраховувати на типографію, щоб виділити ім'я функції. Синтаксис Markdown призначений для того, щоб зробити читабельну документацію навіть тоді, коли інтерпретатор розмітки недоступний, тому всім способом оточуйте ім’я функції парою зворотних посилань. (Це, мабуть, комбінація варіантів 2 і 3.)

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

Я збираюся відповісти лише на конкретний приклад:

Ваша фрейд-реалізація порушена. fread потребує повернення, скільки байтів було прочитано.

Просто замініть першу повну зупинку (Період) крапкою з комою:

Ваша фрейд-реалізація порушена; fread потребує повернення, скільки байтів було прочитано.

Я знаю, що на це вже відповіли, і прийнята відповідь досить гарна, але я просто хочу щось уточнити.

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

Є й інші випадки, коли власне іменник за замовчуванням не повинно писатись з великої літери, але воно може бути (і повинно бути), коли воно вживається на початку речення. Назва мовного ебани є прикладом цього. Функції в мовах, що походять з С, не є. myFunc()і MyFunc()це дві абсолютно різні речі на таких мовах, і початок речення зі словом "MyFunc ()" стосуватиметься лише останньої, а не першої. У VB.NET, однак, це сіра область, оскільки ці дві функції будуть однаковою мовою на цій мові, хоча імена функцій також зберігатимуть визначені користувачем схеми капіталізації на тому чи іншому рівні.

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