Rozpoczynanie zdania nazwą funkcji? [Zamknięte]

42

Czasami podczas pisania czegoś, co odnosi się do języka programowania, w którym rozróżniana jest wielkość liter, kończę zdanie nazwą funkcji. Teraz zasady języka angielskiego mówią, że pierwsze słowo w zdaniu musi być pisane wielką literą; nazwa funkcji jest mała. Jeśli zastanawiasz się, co mógłbym powiedzieć, że pierwszym słowem będzie nazwa funkcji, weź ten przykład:

Twoja implementacja Fread jest zepsuta. fread musi zwrócić liczbę odczytanych bajtów.

Rozumiem, że mógłbym zmienić drugą instancję fread na It, ale chcę wiedzieć, jak najlepiej sobie z tym poradzić, niż tylko przepisać zdanie. Czy powinienem używać wielkich liter nazwy funkcji? Jedynym sposobem, w jaki chciałbym usłyszeć „przepisz zdanie” jako odpowiedź, jest to, że rozpoczęcie zdania od nazwy funkcji narusza pewną angielską zasadę, o której nie wiem. Edycja: Naprawdę dziękuję wszystkim za te odpowiedzi. Zmienili i poprawili mój wgląd w problem. Wiele się z tego nauczyłem. Jestem bardzo zaskoczony, że nie pomyślałem o tych prostych, ale dobrych rozwiązaniach.

Wydaje mi się, że moje stanowisko na przemianę zdania było zbyt trudne i teraz zdaję sobie sprawę z tych dobrych odpowiedzi, że ogólna zmiana zdania wydaje się być najlepszą opcją w tych przypadkach, dodając nawias po funkcji lub mówiąc: Funkcja przed nazwa funkcji i jeśli jest dostępna przy użyciu formatowania nazwy funkcji.

functions użytkownik3462295
źródło
1
@gnat Nie pytam, jak coś nazwać, pytam, jak rozpocząć zdanie od nazwy funkcji.
user3462295,
13
W matematyce istnieje powiązana konwencja, że ​​należy unikać rozpoczynania zdania od nazwy zmiennej lub formuły. Dzieje się tak pomimo faktu, że mamy konwencję typograficzną, w której zmienne i formuły są renderowane kursywą, aby oddzielić je od tekstu. Należy unikać pisania „Niech x będzie potęgą 2. x jest dodatnia, więc ...” Zwykle poprawka polega na przeformułowaniu lub dodaniu słowa uzupełniającego: „Teraz x jest dodatni” lub „Mamy, że x jest dodatni” lub coś w tym rodzaju.
Nate Eldredge
9
Identyfikator z języka programowania powinien być traktowany jako słowo obce i nie powinien podlegać tym samym zasadom, co angielski.
Rufflewind
1
Istnieje kilku niezwykle aktywnych programistów na English.SE ( tchrist ... nie tyle Eric Lippert ) - ale zależy to od rodzaju odpowiedzi, którą chcesz. Piszemy to jako programiści na stronie poświęconej programistom. Jeśli jesteś bardziej zainteresowany formalnościami związanymi z pisaniem artykułów technicznych, wytycznymi dla czasopism i właściwą strukturą zdań w języku angielskim, możesz ponownie rozważyć wybór docelowej grupy ekspertów.
2
To pytanie wydaje się nie na temat, ponieważ jest to język angielski i jego użycie, a do tego mamy całą witrynę StackExchange . Rzeczywiście, istnieją co najmniej cztery podobne pytania tam . Również różne odpowiedzi mogą być jednakowo ważne w zależności od tego, gdzie pojawia się pismo itp.
Caleb

Odpowiedzi:

87

W typografii jest to zazwyczaj obsługiwane przy użyciu innego renderowania, niezależnie od tego, czy jest to początek zdania, aby wskazać, że to, co uderza w oko, to nie tylko słowo w zdaniu, ale szczególny byt.

Twoja freadimplementacja jest zepsuta. freadmusi zwrócić liczbę odczytanych bajtów.

W zależności od tego, jak formalny jest dokument, może przyjąć takie samo podejście. W każdym razie eliminuje to zidentyfikowany problem, dlatego możesz z niego skorzystać tylko z tego powodu.

W świecie tekstowym (jak zauważono w komentarzach i innych odpowiedziach) dodawanie nawiasów do nazw funkcji trochę pomaga, ale ponieważ musimy również odwoływać się do encji, które nie biorą nawiasów, ma to tylko ograniczoną wartość. Ogólnie rzecz biorąc, poza przyjęciem konwencji otaczania tekstu znakami specjalnymi, takimi jak nawiasy kwadratowe i gwiazdki, w świecie zwykłego tekstu nie ma innego wyjścia, jak ominąć ten problem poprzez zmianę zdania.

Reg Edycja
źródło
Tak, rozumiem, o co ci chodzi, wciąż było niezręcznie, ale mniej niezręcznie. Rozumiem jednak, że uczucia nie zawsze są zgodne z zasadami gramatyki i pisania. Nie jestem pewien, czy istnieje lepszy sposób na poradzenie sobie z tym, więc zaakceptuję twoją odpowiedź, chyba że ktoś wymyśli coś lepszego.
user3462295,
25
Często używam po prostu kursywy dla takich rzeczy - zawsze powinieneś zachować wielkość liter, bez względu na to, gdzie są w zdaniu, IMO. freadnie jest słowem; jest to symbol reprezentujący byt. Nie podlega gramatyce.
Ant P
4
I ... co robisz, jeśli masz do czynienia z zwykłym tekstem? Jak w małym pliku pomocy .txt lub w zwykłym e-mailu? Sugeruję dołączenie tego scenariusza również do twojej odpowiedzi.
Ellesedil
2
@Ellesedil W takim przypadku zwykle dodam sufiks ()lub, (...)aby wskazać, że jest to funkcja. Ale to nie zawsze działa, szczególnie w przypadku zmiennych i tym podobnych. To, co wtedy robię, to zawijam nazwę `(zaznacz znak), aby wskazać jej kod.
Cole Johnson
4
@Ellesedil Zacząłem używać składni Markdown do wskazywania elementów kodu, nawet w kontekstach zwykłego tekstu, takich jak komentarze. To jedyny raz, kiedy potrzebowałem używać znaku wstecznego podczas pisania zwykłego angielskiego.
Keen
53

Jeśli istnieje bezwzględne wymaganie, aby każde zdanie zaczynać od wielkiej litery, po prostu zamień na fread„ freadFunkcja”, gdziekolwiek zaczyna zdanie.

kod x
źródło
21

Jeśli nie masz środków typograficznych do odróżnienia (zgodnie z inną odpowiedzią), a może nawet jeśli tak, wskazane jest, że mówisz o funkcji za pomocą parens:

Twoja implementacja fread () jest zepsuta. Funkcja fread () musi zwrócić liczbę odczytanych bajtów.

To pomaga „tłumacząc” dlaczego nie są kapitalizowane na początku zdania drugiego, a także pomaga (w pierwszym zdaniu), aby zrozumieć, dlaczego nazwa własna (nazwa funkcji) nie są kapitalizowane tam obaj . Ponieważ (jako rzeczownik właściwy) prawdopodobnie tak powinno być.

(„prawdopodobnie”, ponieważ moglibyśmy spierać się, czy fread () jest rzeczownikiem rodzajowym, czy właściwym).

Ogólnie rzecz biorąc, użycie parens pomaga mózgowi czytelnika zrozumieć, dlaczego pojawiają się dziwne słowa i jakie są.

GreenAsJade
źródło
5
Korzystanie z parens pomaga również zmniejszyć nadmiarowość tekstu. Zamiast „funkcji fread” można powiedzieć po prostu „fread ()”. Jest to również przydatne, jeśli masz rodzaj podświetlenia, aby podkreślić różnicę między takimi rzeczami, jak nazwy zmiennych i funkcje.
Paul92
3
Myślę, że nawiasy tylko wprowadzają więcej zamieszania. fread()może być wyciągiem z połączenia. Lub może dotyczyć przeciążonej funkcji bez parametrów.
kapex
4
@kapep Ogólnie w dokumentach odnoszących się do kodu func_name()jest odczytywany jako „funkcja według nazwy func_name”, niezależnie od tego, czy sama funkcja ma jakieś parametry.
Eric Finn
3
@EricFinn Z mojego doświadczenia wynika, że ​​ogólnie odnosi się do funkcji bezparametrowych, ale na pewno zależy od języka i jego konwencji. Na przykład oficjalne wytyczne dotyczące komentarzy Java zniechęcają do stosowania nawiasów: „Odnosząc się do [określonej formy metody], używaj nawiasów i typów argumentów. [...] Jeśli jednak odwołujesz się do obu form metody, pomiń całkowite nawiasy. Wprowadzanie pustych nawiasów jest mylące, ponieważ oznaczałoby to szczególną formę metody „ oracle.com/technetwork/java/javase/documentation/…
kapex
3
Chociaż dodanie wizualnej wskazówki jest z pewnością dobrym pomysłem (najlepiej jest to dedykowana czcionka lub inna atrakcja), zgadzam się z kapep, że dołączanie pustych parenów jest naprawdę problematycznym wyborem, ponieważ w każdym języku, który znam, f()znaczy coś innego niż f. Dlaczego nie otoczyć nazwy odpowiednią postacią, np. „Fread” w stylu markdown (to właśnie robię w komunikatach zatwierdzania VCS)? Lub po prostu (fread). Oczywiście, każda taka rzecz powinna być wykonywana konsekwentnie, nie tylko dla funkcji na początku zdania.
leftaroundabout
10

Możesz rozpocząć zdanie od opisu:

Funkcja fread[…]

Metoda fread[…]

Właściwość breadColor[…]

David Sergey
źródło
@Zack: Prezydent Obama.
Marc van Leeuwen,
@MarcvanLeeuwen Tytuły to szczególny przypadek. (Również „Queen Elizabeth”, „Mister Rogers”.) Nie mam odpowiedniej analizy z góry mojej głowy, ale intuicyjnie myślę, że są one uważane raczej za część nazwy niż tag kategorii.
zwolnić
8

Można to porównać do wbudowanej matematyki w publikacjach. Bardzo rzadko widzisz zdania zaczynające się od zmiennej lub innej wbudowanej matematyki.

Podsumowując, powinieneś unikać nazw funkcji na początku zdania.

Może to pytanie zawiera dalsze szczegóły: Czy można rozpocząć zdanie od greckiej litery (zmiennej)? .

Lukas
źródło
3
+1. W dowodach matematycznych (Chartrand i in., 2000), w których rozdział 0 jest prawdziwym źródłem dobrych porad dotyczących pisania matematycznego, pierwszą zasadą w sekcji Używanie symboli jest „Nigdy nie zaczynaj zdania od symbolu”. (Przykładem jest zdanie rozpoczynające się od równania; autorzy sugerują zastąpienie go „Równaniem ___”.). Chociaż nie wszystkie porady matematyczne dotyczące pisania muszą koniecznie dotyczyć pisania o kodzie źródłowym, myślę, że jest to jeden z nich.
ruakh
1
Nie jestem pewien, czy zgadzam się z analogią. Symbole takie jak $ x $ są przejściowe w stosunku do równania, więc dziwnie jest nazywać je tak, jakby miały globalne znaczenie. Jeśli symbol taki jak $ \ pi $ rozpoczyna zdanie, czułbym się komfortowo jako czytelnik.
djechlin
1
@djechlin Nie jestem pewien, czy rozpoczęcie zdania od symbolu implikuje, że ma ono globalne znaczenie, a tak naprawdę nie ma z tym nic wspólnego.
Kyle Strand
@KyleStrand byłoby miło wiedzieć, dlaczego nigdy nie należy zaczynać zdania od symbolu. „$ \ pi $ is ...” v. „Stała matematyczna $ \ pi $ is ...” - ty wybierasz.
djechlin
1
@djechlin: Jednym z powodów jest to, że jeśli poprzednie zdanie kończy się na matematyce, matematyka na początku następnego zdania może wyglądać jak część tej samej formuły z kropką pomiędzy nimi. (Jest to tym bardziej problem z przecinkami.) Innym problemem jest to, że ponieważ nazwy zmiennych są zwykle małe, oko czytelnika traci wzrokowy wygląd szukania dużej litery, aby znaleźć początek następnego zdania.
Nate Eldredge
3

Strona podręcznika systemu Linux poświęcona fread (3), do której prowadzą inni łącza, jest doskonałym przykładem czterech popularnych rozwiązań.

  1. Rozpocznij zdanie od „Funkcja foo” lub „Funkcja foo”. „Funkcja fread musi powrócić ...” .
  2. Oznacz nazwę funkcji dodatkowymi znakami zgodnie z konwencją używaną przez społeczność użytkowników języków programowania. W przypadku C pusta para nawiasów, więc „fread () musi zwrócić ...” .
  3. Użyj typografii (pogrubienie, znaki o stałej szerokości lub kursywą), aby podświetlić nazwę funkcji, ponieważ: „ fread musi wrócić ...”
  4. W systemach, które używają man, jeśli twoja funkcja ma stronę podręcznika, zapoznaj się z rozdziałem instrukcji w nawiasach. Więc „fread (3) musi wrócić ...”

Wszystkie cztery podejścia będą natychmiast rozpoznawane przez hakerów i powinieneś być w stanie wybrać takie, które pasuje do twojego stylu domu lub twojego osobistego głosu.

Jak powiedziałeś, nie możesz polegać na typografii, aby wyróżnić nazwę swojej funkcji. Składnia Markdown ma na celu tworzenie czytelnej dokumentacji, nawet gdy interpreter Markdown jest niedostępny, więc za wszelką cenę otaczaj nazwę swojej funkcji parą znaków wstecz. (To, jak sądzę, kombinacja opcji 2 i 3.)

Opcja 2 różni się w zależności od języka programowania. Na przykład dokumenty Ruby i Smalltalk często poprzedzają nazwy metod instancji hashem , takim jak #fread . Tymczasem Lispers może wolić, aby nazwa funkcji była pusta, ale zrozumie, jeśli napiszesz wywołanie funkcji szkieletu, takie jak (fread ...) lub (fread) . Opłucz i powtórz dla wszystkich języków, które dokumentujesz.

dcorking
źródło
Podoba mi się twoja odpowiedź. Dzięki temu pisanie o funkcjach wygląda lepiej.
user3462295
2

Odpowiem tylko za podany konkretny przykład:

Twoja implementacja Fread jest zepsuta. fread musi zwrócić liczbę odczytanych bajtów.

Wystarczy zamienić pierwszy kropkę (kropkę) średnikiem:

Twoja implementacja Fread jest zepsuta; fread musi zwrócić liczbę odczytanych bajtów.

EdHunter
źródło
3
Nie! sprawiłoby to, że byłby to zdanie lub przecinek. Bardzo słaba gramatyka. Średnik byłby OK.
Martin McCallion
Używanie przecinka nie zawsze działa; ale po co używać przecinka?
reinierpost
To nie przecinek. To średnik; właściwe użycie średnika w tym.
RubberDuck,
1
Osobiście użyłbym tutaj dwukropka zamiast średnika (chociaż dobrze odczytuje również średnik).
Marc van Leeuwen,
0

Wiem, że już na nie udzielono odpowiedzi, a zaakceptowana odpowiedź jest całkiem dobra, ale chcę coś wyjaśnić.

W prawidłowej gramatyce angielskiej, sedno jest następujące: Czasami właściwym rzeczownikom nadaje się nazwy, które nie zaczynają się od dużej litery, aw większości takich przypadków są one tak samo przywiązane do tego, że nie są pisane wielką literą, jak „normalne” rzeczowniki właściwe kapitalizacja. W takich przypadkach - które z pewnością obejmowałyby większość nazw funkcji w językach potomnych C - absolutnie nie wpisujesz nazwy, nawet na początku zdania. W rzeczywistości jest to zła gramatyka angielska i pisownia. Jest to właściwie część tej samej zasady, dlaczego pisownia konsoli do gier Sony „PlayStation” jest poprawna, ale nie „Playstation”.

Są inne przypadki, w których właściwy rzeczownik nie powinien być domyślnie pisany wielkimi literami, a jednak może być (i powinien być), gdy jest używany na początku zdania. Nazwa tego języka jest tego przykładem. Funkcje w językach potomnych C nie są. myFunc()i MyFunc()są dwie zupełnie różne rzeczy w takich językach, a rozpoczęcie zdania słowem „MyFunc ()” odnosi się tylko do tego ostatniego, a nie do pierwszego. W VB.NET jest to jednak szara strefa, ponieważ te dwie funkcje byłyby takie same w tym języku, chociaż nazwy funkcji zachowałyby również określone przez użytkownika schematy wielkich liter na jakimś poziomie.

Ponadto, mimo że angielskie reguły są w tym przypadku ugruntowane, zwykle są one niejasne. Angielski nie został zaprojektowany z myślą o takich rzeczach, więc dla innych takich rzeczy jest miejsce na improwizację.

Panzercrisis
źródło