関数名で文を始めますか?[閉まっている]


42

大文字と小文字を区別するプログラミング言語に関連する何かを入力しているときに、関数名で文を開始することがあります。現在、英語の規則では、文の最初の単語は大文字にする必要があります。ただし、関数名は小文字です。最初の単語が関数名になるということを私が何と言っているのか疑問に思っているなら、この例を見てください:

フレッドの実装が壊れています。freadは、読み取られたバイト数を返す必要があります。

私はfreadの2番目のインスタンスをItに変更できることを理解していますが、文を書き換える以外にこれを処理する最良の方法を知りたいです。関数名を大文字にする必要がありますか?「文を書き直して」という答えを聞きたいのは、関数名で文を開始すると、知らない英語の規則に違反する場合だけです。編集:これらの答えを本当にありがとう。問題に対する私の洞察が変わり、改善されました。私はこれから多くを学びました。私はこれらのシンプルだが良い解決策を考えていなかったことに非常に驚いています。

私は文を交互に変えるというスタンスは非常に難しかったと思いますが、これらの良い答えのために、文の全体的な変更が関数の後にカッコを追加するか、または関数名、および利用可能な場合は関数名の書式設定を使用します。


1
@gnat私は何に名前を付けるかを尋ねているのではなく、関数名で文を開始する方法を尋ねています。
user3462295 14

13
数学には、変数名または式で文を開始することを避けるべきである関連する規則があります。これは、変数と数式をイタリック体で表示してテキストから区別するという表記上の規則があるにもかかわらずです。一つは、「してみましょう書き込みを避けるだろう、xが 2の累乗で xは通常の修正プログラムは、いくつかのフィラー語を言い換えたり追加することですので...、ポジティブである」:「今、xが正である」または「我々は持っている、xが正です」かある種の。
ネイト・エルドレッジ14

9
プログラミング言語の識別子は外国語として扱われるべきであり、同じ英語の規則に従うべきではありません。
ラッフルウィンド14

1
English.SEには非常に活発なプログラマーがいます(tchrist ... Eric Lippertほどではありません)-しかし、それはあなたが望む答えのタイプに依存します。私たちは、プログラマー向けのサイトでプログラマーとしてこれを書いています。テクニカルライティング、ジャーナルガイドライン、および適切な英語の文構造の形式にもっと関心がある場合は、ターゲットの専門家の聴衆を再考することをお勧めします。

2
この質問は英語と使用法であるため、トピックから外れているように見えます。そのためのStackExchangeサイト全体があります。実際、そこには少なくとも4つの 類似した 質問 があります。また、異なった答えはなど、書き込みが表示される場所に応じて同様に有効かもしれ
カレブ

回答:


87

タイポグラフィでは、これは一般に、文の始まりであるかどうかにかかわらず、異なるレンダリングを使用して処理され、目に当たるのは文中の単語ではなく、特別なエンティティであることを示します。

あなたのfread実装が壊れています。fread読み取られたバイト数を返す必要があります。

ドキュメントの形式に応じて、同じアプローチを採用できます。いずれにせよ、これにより特定した問題が解消されるため、その理由だけで使用することをお勧めします。

プレーンテキストの世界(コメントやその他の回答でいくつか述べられているように)では、関数名にかっこを追加すると少し助けになりますが、かっこを使用しないエンティティも参照する必要があるため、値が限られています。一般に、括弧やアスタリスクなどの特殊文字でテキストを囲む規則を採用する以外に、プレーンテキストの世界では、文を再構築することによって問題を回避する以外の選択肢はほとんどありません。


はい、私はあなたの主張を見ます、それはまだ厄介ですが、それほど厄介ではありません。しかし、感情は必ずしも文法や文章のルールに沿っているとは限らないことを理解しています。これを処理するより良い方法があるかどうかはわかりませんので、誰かがより良い何かを思い付かない限り、あなたの答えを受け入れます。
user3462295 14

25
私はしばしばこのようなことをイタリック体にします- 大文字と小文字を区別する用語は、IMOのどこにあるかに関係なく、常に大文字と小文字を区別する必要があります。fread言葉ではありません。これは、エンティティを表すシンボルです。文法の対象ではありません。
アリP 14

4
そして...プレーンテキストを処理する必要がある場合はどうしますか?小さな.txtヘルプファイル、またはプレーンテキストの電子メールのように?そのシナリオも回答に含めることをお勧めします。
エルセディル14

2
@Ellesedilその場合、通常、接尾辞を付けて、()または(...)関数であることを示します。しかし、特に変数などを扱う場合は、常に機能するとは限りません。次に、`コードを示すために名前を(ティック文字)でラップします。
コールジョンソン14

4
@Ellesedilマークダウン構文を使用して、コメントなどのプレーンテキストコンテキストであっても、コード要素を示すことにしました。普通の英語を書くときにバックティックシンボルを使用する必要があったのはこれだけです。
キーン14

53

キャップとの各文を開始するための絶対的な要件がある場合、単純に交換してくださいfread「とfread、それが文を開始どこ機能」。


21

(別の答えのように)区別するための活版印刷の手段がない場合、もしそうだとしても、括弧を使用して関数について話していることを示すことは有用です。

fread()の実装が壊れています。fread()は、読み取られたバイト数を返す必要があります。

これは、2番目の文の先頭で大文字になっていない理由を「説明」するのに役立ち、また、(最初の文で)固有名詞(関数名)が大文字になっていない理由を理解するのにも役立ちます。以来(固有名詞として)間違いなくそうだったはずです。

(「おそらく」fread()が総称名詞であるか固有名詞であるかを議論できるためです)。

全体的に、括弧を使用すると、読者の脳は奇妙な単語が現れる理由とその意味を理解するのに役立ちます。


5
括弧を使用すると、テキストの冗長性を減らすこともできます。「関数fread」の代わりに、「fread()」とだけ言うことができます。また、変数名や関数などの違いを強調するために、一種の強調表示がある場合にも役立ちます。
Paul92 14

3
括弧は混乱を招くだけだと思います。fread()呼び出しステートメントである可能性があります。または、パラメータのないオーバーロードされた関数を参照している可能性があります。
カペックス14

4
@kapep通常、コードを参照するドキュメントでfunc_name()func_name、実際の関数自体にパラメーターがあるかどうかに関係なく、「名前による関数」と読みます。
エリックフィン14

3
@EricFinn私の経験では、一般にパラメーターなしの関数を指しますが、言語とその規則に依存するのは当然です。たとえば、公式のJavaコメントガイドラインでは、括弧の使用を推奨していません。「[メソッドの特定の形式]を参照するときは、括弧と引数タイプを使用します。[...]ただし、メソッドの両方の形式を参照する場合は、 。それは方法」の特定の形態を意味するものであろうから、括弧は全く空の括弧を含めるように誤解されoracle.com/technetwork/java/javase/documentation/...
kapex

3
視覚的な手がかりを追加することは確かに良いアイデア(最高は、専用のフォントまたはその他のハイライトである)ですが、私はすべての言語で、私が知っているので、空の括弧を追加することは、本当に問題な選択であることをkapepに同意するf()手段には異なる何かをf。マークダウンスタイルの「fread」など、適切な文字で名前を囲まないのはなぜですか(私はVCSコミットメッセージでこれを行う傾向があります)。または単に(恐怖)。もちろん、そのようなことは文の最初の関数だけでなく、一貫して行われるべきです。
leftaround 14

10

説明から文を開始できます:

関数fread[…]

メソッドfread[…]

プロパティbreadColor[…]


@ザック:オバマ大統領。
マークヴァンレーウェン14

@MarcvanLeeuwenタイトルは特別なケースです。(「エリザベス女王」、「ロジャース女王」も)。私は頭のてっぺんから適切な分析をしていませんが、直感的にはカテゴリタグではなく名前の一部と考えられていると思います。
zwol

8

これを出版物のインライン数学と比較できます。変数またはその他のインライン数学で始まる文はほとんどありません。

したがって、私は結論として、文の先頭に関数名を避けるべきです。

たぶん、この質問はさらに詳細を提供します:ギリシャ文字(可変)で文を開始しても大丈夫ですか?


3
+1。で証明その第0章数学的な書き込みのための良いアドバイスの真の源泉である、下の非常に最初のルール(Chartrandら、2000)、シンボルの使用がある「記号で文を始めることはありません。」(例は方程式で始まる文です。著者は「方程式___」でそれを前書きすることを提案しています。)すべての数学的記述アドバイスがソースコードについての記述に必ずしも当てはまるわけではありませんが、私はこれが1ビットだと思います。
ruakh

1
アナロジーに同意するかどうかわかりません。$ x $のようなシンボルは方程式の一時的なものであるため、グローバルな意味を持つかのように参照するのは奇妙です。$ \ pi $のような記号が文を開始する場合、読者として快適に感じるでしょう。
-djechlin

1
@djechlinシンボルで文を開始すると、それがグローバルな意味を持つことを意味するのか、実際にはそれと関係があるのか​​わかりません。
カイルストランド14

@KyleStrand記号で文を始めてはいけない理由を知っておくといいでしょう。「$ \ pi $ is ...」v。「数学定数$ \ pi $ is ...」-選択します。
djechlin

1
@djechlin:1つの理由は、前の文が数学で終わる場合、次の文の最初の数学はドットを挟んだ同じ式の一部のように見える可能性があるためです。(これはコンマではさらに問題です。)別の問題は、変数名は通常小文字であるため、次の文の始まりを見つけるために大文字を探す視覚的な手がかりが失われることです。
ネイト・エルドリッジ2014

3

他の人がリンクしたfread(3)のLinux manページは、4つの一般的なソリューションの優れた例です。

  1. 「The関数foo」または「The foo関数」で文を始めてください。「関数のfreadのニーズが戻って...」
  2. プログラミング言語コミュニティが使用する規則に従って、関数名に余分な文字を付けてください。Cの場合は、空の括弧のペアなので、「fread()が返す必要がある...」
  3. タイポグラフィ(太字、固定幅文字または斜体)を使用して、関数名を強調表示します。fread needs to return ...」
  4. を使用するシステムでman、関数にマニュアルページがある場合は、カッコ内のマニュアルの章を参照してください。したがって、「fread(3)は返す必要があります...」

4つのアプローチはすべて、ハッカーにすぐに認識され、家のスタイルや自分の声に合ったものを選択できるはずです。

あなたが言ったように、タイポグラフィに頼って関数名を強調することはできません。Markdownの構文は、マークダウンインタープリターが利用できない場合でも読みやすいドキュメントを作成することを目的としているため、必ず、関数名をバッククォートで囲んでください。(これは、オプション2と3の組み合わせだと思います。)

オプション2は、プログラミング言語によって異なります。たとえば、RubyおよびSmalltalkのドキュメントでは、インスタンスメソッド名の前に#freadのようなハッシュが付いていることがよくあります。一方、Lispersは関数名をむき出しにすることを好むかもしれませんが、(fread ...)(fread)などのスケルトン関数呼び出しを記述すれば理解できます。文書化するすべての言語について、すすぎ、繰り返します。


私はあなたの答えが好きです。そうすることで、関数についての記述が見やすくなります。
user3462295 14

2

与えられた特定の例についてのみ答えます。

フレッドの実装が壊れています。freadは、読み取られたバイト数を返す必要があります。

最初のフルストップ(ピリオド)をセミコロンに置き換えるだけです:

フレッドの実装が壊れています。freadは、読み取られたバイト数を返す必要があります。


3
番号!それは、それを実行文またはコンマスプライスにします。非常に貧弱な文法。セミコロンでも構いません。
マーティンマッカリオン14

したがって、コンマを使用しても常に機能するとは限りません。しかし、なぜコンマを使用するのですか?
reinierpost 14

カンマではありません。セミコロンです。その際のセミコロンの適切な使用。
ラバーダック14

1
ここでは、セミコロンではなくコロンを個人的に使用します(ただし、セミコロンでも読みやすくなります)。
マークヴァンレーウェン14

0

これはすでに回答済みであり、受け入れられた回答はかなり良いことを知っていますが、何かを明確にしたいだけです。

適切な英語の文法では、最終行は次のとおりです。固有名詞には、大文字で始まらない名前が付けられる場合があり、ほとんどの場合、「通常の」固有名詞のように、大文字にならないことにすべて結びついています。大文字である。そのような場合(C降格言語のほとんどの関数名が確実に含まれるはずです)、文の先頭であっても名前を大文字にしないでください。実際、そうするのは悪い英語の文法とスペルです。これは、実際には、ソニーのゲームコンソール「PlayStation」をスペルするのが正しいのと同じ原理の一部ですが、「Playstation」ではありません。

固有名詞がデフォルトで大文字になっていると想定されていない他の場合もありますが、文の先頭で使用される場合は使用できます(使用する必要があります)。言語Brainfuckの名前は、この例です。C言語の関数はそうではありません。 myFunc()そして、そのような言語ではまったく異なるMyFunc()2つのことであり、「MyFunc()」という単語で文を開始すると、前者ではなく後者のみが参照されます。ただし、VB.NETでは、これらの2つの関数はその言語では同じものになるので、これは灰色の領域です。ただし、関数名はユーザーが指定した大文字と小文字のスキームを何らかのレベルで保持します。

また、この場合、英語の規則は固く定められていますが、規則としてこのようなことをやや曖昧にする傾向があります。英語はこのようなことを念頭に置いて設計されていなかったため、このような他のことについては、即興の余地があります。

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.