題:
對共享文檔和代碼進行語法和拼寫更改是否有禮節?
Longisland
2017-08-08 19:23:29 UTC
view on stackexchange narkive permalink

我在一家開放而友好的氛圍中的小型開發公司工作,並且是最初級的員工。我們有一個基於雲的存儲庫,用於存儲用戶文檔,私有文檔(例如服務器規格和開發人員部署指南)。其中許多都是匆忙編寫的,或者不是經過校對的,通常當我閱讀工作文檔時,會遇到簡單的拼寫錯誤,錯別字和不正確的語法。在其他情況下,在代碼中,我會在調試語句,控制台輸出和呈現給用戶的消息中遇到許多錯字。 ul>

  • 我編輯了這些文檔來修復語法和拼寫,特別是在那些不面向公眾的文檔上?
  • 原始作者是誦讀困難的人?提交代碼中的拼寫和語法錯誤的修復程序,並且不更改代碼的實際功能?
  • 評論不作進一步討論;此對話已[移至聊天](http://chat.stackexchange.com/rooms/63577/discussion-on-question-by-donglecow-is-making-grammatical-and-spelling-changes-t)。
    我將把它留在這裡: https://zh.wikipedia.org/wiki/HTTP_referer
    一個警告是,作為新員工,您可能不知道可以避免尷尬的錯誤的事情。例如,如果我將您的帖子固定為使用牛津逗號(您顯然不喜歡),該怎麼辦? 儘管這樣做確實是正確的,但也許對您來說是錯誤的,因為您使用了不同的樣式指南。慢慢進行(儘管我強烈支持改進這些內容,儘管您要編輯的內容超出了我的期望,但我仍想對您的問題進行編輯,但多數情況下,我想將“校對”的拼寫改為“校對”)。
    @Donglecow-您是否正在處理要更改的代碼領域?變量和方法名稱中是否存在語法和拼寫錯誤?
    以非母語發言者發言:當我盡最大努力正確書寫某些錯誤是不可避免的。希望大多數問題在審核過程中得到糾正。如果我是您,我會將所有變更與代碼變更捆綁在一起作為一件事進行審查,但這取決於公司的文化。如果我以外的人評論我的英語知識,我會感到受傷害-我認為有閱讀障礙的人也不想評論他們的殘疾-因此,我不會提請注意它並使其盡可能地保持非人格化(沒有理由提及為什麼存在錯誤)。
    十一 答案:
    Joe Strazzere
    2017-08-08 19:39:24 UTC
    view on stackexchange narkive permalink

    我要對代碼中的拼寫和語法錯誤進行修復,而不對代碼的實際功能進行任何更改?

    請仔細閱讀此處。

    通常,任何代碼更改都會對下游產生影響。可能需要進行代碼審查。可能需要測試。可能需要進行安全審查。等等,不斷變化的拼寫和語法錯誤可能會導致其他人的計劃外工作。

    雖然您的意圖是不對實際功能進行任何更改,但是會發生錯誤。

    在更改任何代碼之前-請詢問。

    • 我編輯這些文檔是為了解決語法和拼寫問題,尤其是在不面向公眾的文檔上?
    • 原始作者有閱讀障礙嗎?

    這主要取決於您所在組織的文化。

    在某些公司中,閱讀此類文檔的每個人都在不斷進行更改。歡迎。在其他公司中,未經作者許可,將被視為不禮貌。

    評論不作進一步討論;此對話已[移至聊天](http://chat.stackexchange.com/rooms/63861/discussion-on-answer-by-joe-strazzere-is-making-grammatical-and-spelling-changes)。
    Laurent S.
    2017-08-08 19:32:39 UTC
    view on stackexchange narkive permalink

    我認為這種變化可以提高質量。內部文檔雖然沒有面向最終用戶,但仍然具有價值,而提高其質量使其更有價值。我個人更傾向於信任文檔,如果其中沒有大量的錯別字。有時,錯別字或錯誤的語法也可能會改變意思或導致誤解。

    總結一下:我發現它是很肯定的。

    請注意,如果您碰巧花費了很多時間這樣做,人們可能會想知道您是否還有更好的事情要做,例如編碼...

    在開發代碼的那部分時,我經常這樣做。你知道,“讓這個地方保持比你發現的地方更好的狀態”,所有...
    我記得當所有錯別字成為公開的尷尬時(由於它們通過javadoc公開),Sun必須經過*大量*的註釋清理。
    關於您的最後一句話,難道不應該為閱讀的代碼比編寫的代碼(或類似的東西)做一個論點嗎?
    對@setht進行良好註釋和/或自我註釋的代碼是一回事,文檔是另一回事。我希望開發人員比他的校對文檔花費更多的時間進行編碼...
    JanErikGunnar
    2017-08-09 01:49:41 UTC
    view on stackexchange narkive permalink

    假設您所做的最壞的更改:

    • 您犯的錯誤會破壞某些東西
    • 您的次要提交可能會使變更日誌雜亂無章等
    • 您的雇主可能會認為您的時間花在了做更多有用的事情上

    由於這個原因,如果基本上我仍然在更改代碼/文檔,那麼我只會進行“未經請求的”更改。因此,如果我被要求更改某些類,並且我知道它的功能無論如何都必須重新測試,那麼如果我真的相信它會提高質量或節省每個人的時間,那麼我也可能會對其進行重構並修復一些拼寫錯誤到底。正如其他答案所提到的那樣:“童子軍規則”-離開營地時要比到達時更整潔。

    但是,請不要因不必要的露營而意外地引發灌木叢大火:)其他進行更改,以決定誰做的人為例。說明修復程序的好處以及任何風險。好處示例包括:拼寫錯誤的代碼禁止搜索代碼庫,對拼寫錯誤的消息或文檔產生負面的用戶感知等。讓他們決定是否值得花費時間/風險。

    我發現您的指南非常合適(如果我沒看錯的話,其他答案中也沒有):僅當您無論如何觸摸該文件時,才進行化妝品類型的未經請求的更改。(並使其成為兩個不同的提交,很多都會添加。)
    我完全同意。我過去曾與OP同舟共濟,在解決這些模塊的bug修復時便解決了外觀問題……我等了六個月才解決了一個明顯的錯字(名為get_locgat_file()的本地函數,指的是android的logcat),直到有錯誤修復要提交為止。
    _“如果基本上無論如何我都在更改代碼/文檔,我只會進行“不請自來的”更改。” _-+1,相關術語:“童子軍規則”或“總是離開營地的清潔工,要比發現的要清潔”
    motosubatsu
    2017-08-08 19:29:34 UTC
    view on stackexchange narkive permalink

    如果我們說的是真正的細微變化,例如修正錯別字或缺少逗號等,那麼我不會說僅在發現它們時對其進行修正是一件壞事。我不會做的是告訴所有人您已經進行了更改,因為這似乎充其量看起來像是在尋求注意力,而在最壞的情況下卻看起來像是小拼寫/語法納粹。

    另一個要解決的優勢發現的情況是,您不想作為正在尋找這些錯誤的人而逃脫。

    代碼可能有些不同-儘管您確實聲明您不會更改實際代碼,因此我假設它只是註釋之類的東西,因此它對功能的影響為零,在這種情況下,我建議可以。

    Carlos3dx
    2017-08-08 19:54:48 UTC
    view on stackexchange narkive permalink

    我要對代碼中的拼寫和語法錯誤進行修復,而對代碼的實際功能不做任何更改?

    是否存在任何公開可見的錯誤(在前端)還是在客戶端(在客戶端控制台日誌中)?

    如果是,請詢問團隊/項目負責人以授權您對其進行糾正。

    如果不是,請執行什麼也不問,或者問團隊/項目負責人是否可以做一些重構,然後解決代碼可能存在的任何其他問題。

    在任何情況下,請不要批評您的同事,特別是如果他的閱讀障礙。 / p>

    cdkMoose
    2017-08-08 21:15:08 UTC
    view on stackexchange narkive permalink

    除非代碼直接與您正在處理的錯誤或增強票據綁定,否則請勿更改代碼。 (您確實有某種可以在現有系統上工作的票務系統,對嗎?)還應該進行更改以完成票務的工作。

    如果您堅信應該更改此代碼, ,創建票證進行審核,如果獲得批准,您就可以完成工作。有很多方法似乎使瑣碎的編輯可能出錯,有時甚至會延遲。

    例如,在我公司,我們基於監視/抓取日誌文件構建了一個警報系統。日誌中的錯誤消息可能會生成任何信息,從輕微警告到全手動提示。多年來,不幸的是,我們創建了帶有各種拼寫錯誤的日誌錯誤消息。如果一些狂熱的開發人員“修復”了錯誤消息,我們的警報系統可能會突然變得安靜。

    聽起來您需要提交故障單以修復警報系統,因為那是一個等待中的火藥桶。
    警報系統工作正常。如果要進行粒度警報,則需要在日誌中進行特定的跟踪以進行檢查。只要人們不進行不知情的更改即可正常工作。
    答案似乎與問題無關。OP正在詢問有關修復*註釋*和共享*文檔*的問題。
    @AnoE,第三個項目符號指定代碼,而不是註釋。該段包括“調試語句,控制台輸出和呈現給用戶的消息”。顯然,這是真實的代碼,而不是註釋或文檔。
    好吧...我想這就是他要問的代碼非功能部分的問題所在(即* not *輸出包括日誌文件中的內容)。但就問題的某些部分而言,這是否是出於意圖的問題,是對的。
    調試語句和控制台輸出可能不是系統功能的一部分,但它們是功能代碼。我只是在說明有關日誌文件的示例。
    值得一提的是,警報系統可以掛起日誌輸出。我什至沒有意識到這甚至是一件事,而且絕對不是我們在工作場所中使用的東西,但是仍然很高興知道這一點。儘管(抱歉,這不是主題),但這是否會使警報系統變得十分脆弱,如TemporalWolf所指出的那樣?
    @DongleCow,並不十分脆弱,而可能丟失重要事件。在這種情況下,警報系統會順暢運行。當開發人員意識到系統時,風險並不大,但是初級開發人員總不會想到什麼時候掃帚清理代碼。
    Max
    2017-08-09 00:22:30 UTC
    view on stackexchange narkive permalink

    這真正要歸結為上下文。

    例如,我為一家跨國公司工作,其團隊遍布多個國家。我是唯一的以英語為母語的人,所以我每天在代碼名和註釋中遇到語法和拼寫錯誤。

    我通常將它們保留原樣,因為更正錯誤不會帶來任何好處,並且由於上下文的原因,總是很容易理解作者的意圖。 (在我的頭頂上,我可以想到一個文件夾,該文件夾可以被幾個名為“ ressources”的文件訪問。

    如果更改的名稱是實際的代碼對象,並且名稱是描述性的雖然拼錯了,但我看不到增加自己的工作量的好處。

    我不相信如果我開始更正自己提交中的錯誤,我的外國同事將不會受到冒犯,但是隨著時間的推移,如果我要一遍又一遍地做下去,他們可能會開始覺得自己的英語水平不高。

    底線,問問自己這種情況的背景是否值得進行額外的工作

    我認為糾正他人代碼中的拼寫和語法錯誤不會給任何人以您是對此更好的編碼者的印象,僅此而已。可以更好地掌握英語。

    ca1386
    2017-08-08 19:37:54 UTC
    view on stackexchange narkive permalink

    面對面的文件和日誌條目在拼寫和語法正確性方面應比內部文件和代碼具有更高的標準。當然,也建議不斷清理正在處理的代碼。這意味著無論何時使用功能/錯誤修正,都應使受影響的部件比以前保持清潔(boyscout規則)。情況不應該是這樣,當您編輯代碼時,所做的更改僅包含語法和拼寫的修正。

    此外,您應該在定期養成這種習慣之前,先詢問您的經理,因為他/她可以提供幫助您與可能會更正他們的貢獻的同事取得聯繫。

    我同意(這在此處適用)時,線條可能會模糊。特別是在軟件開發中,會根據內部註釋自動生成一些文檔(可能是供公眾使用);)
    David K
    2017-08-08 19:38:52 UTC
    view on stackexchange narkive permalink

    您要處理的類別有兩類:面向公眾的文檔和內部文檔以及代碼。

    對於內部文檔和代碼,不要為多餘的更改而煩惱。只要文件是可以理解的並且可以正常工作,那麼實際上沒有任何收穫。這樣的編輯並沒有真正添加任何內容,並且可能使您的版本控制歷史記錄變得混亂。但是,如果您已經對特定文檔進行了更改,並且也看到了一些拼寫錯誤,請繼續。在那種情況下,它實際上是對已經必要的更改的附加。

    對於面向公眾的文檔和UI消息,確保幾乎沒有錯誤並且所有語法正確都是很重要的。如果這顯然是不正確的,那麼我一定會更改它。如果是比較主觀的更改(例如,更改措辭或牛津逗號),那麼在保存任何修改之前,我會先諮詢主要作者或您的經理。再次,我發現很多類似這樣的小修改可能會使版本控制混亂,所以我個人更喜歡將更改與其他更重要的更新一起保存,或者擱置修改並一次批量上傳一堆複製編輯。您可以與您的經理交談,以了解他們的偏愛。

    我不同意將修飾(拼寫/語法/格式/等)和功能更改組合到單個提交中,提交中的混亂情況比更改日誌更糟。我更喜歡將它們分開。這樣,如果我將代碼歸咎於找出原因,那麼我可以查看提交註釋,並且(例如,“拼寫修復”與“ Issue-12345如果使用Windows 8,則在星期二下午修復了樣條線的網狀結構”)),並立即知道我需要查看以前的版本,而有可能認為所涉及的行是作為偶然糾正拼寫錯誤的提交的一部分而創建/編輯的。
    StephenG
    2017-08-11 17:05:54 UTC
    view on stackexchange narkive permalink

    我在一家開放而友好的氛圍的小型開發公司中工作,並且是最初級的員工。

    您有一位經理。那就是您應該問的人!

    我們的意見可以作為建議,但您的老闆是必須做出決定的人。他們必須決定如何最好地利用您的時間

    我遇到了簡單的拼寫錯誤,錯別字和不正確的語法。

    如果您被授權更改這些文檔並且某些您沒有更改預期的含義,那麼我認為可以。但是,確定預期的含義並非易事,並且很容易在沒有預期的情況下更改含義。

    在其他情況下,在代碼中,我在調試語句,控制台中遇到許多錯別字輸出和呈現給用戶的消息。

    代碼錯誤(包括任何類型的消息)都需要使用錯誤跟踪系統來正確解決。然後可以適當地對它們進行優先級排序並在此基礎上進行處理。

    並且有可能搞砸這些更改並弄亂這樣做的代碼。

    在以下情況下會被認為是不良禮節或小事:

    我編輯了這些文檔以修復語法和拼寫,尤其是那些不是是面向公眾的嗎?

    不需要特別固定這種內部私人文件。

    原始作者是閱讀障礙者?

    原始作者的能力或局限性與您的時間使用方式無關。 / p>

    我要對代碼中的拼寫和語法錯誤進行修復,而不更改代碼的實際功能?

    對代碼的任何更改都是正式的更改。對註釋和其他元素的更改可以引入錯誤-人們在這樣做時會犯錯誤。我建議您不要在生產線管理層的明確指示下提出建議。

    PoloHoleSet
    2017-08-08 20:05:33 UTC
    view on stackexchange narkive permalink

    如果文檔不是公開的(如您所提到的那樣),那麼進行這些更正的真正好處是什麼(除了不打擾您)?

    如果您正在不會更改代碼的功能,並且改進的語法表示形式完全不會影響公司的形象,那麼您就沒有為代碼添加任何價值。

    如果您花時間“修復”了某些東西,沒有價值,您只是浪費了自己的時間,浪費了老闆的時間和金錢,這不是任何人都無法走的路,而是食物鏈中最年輕的人。

    您可能會煩人的人會問“為什麼要解決這個問題?”,您可能會提出一個普遍的問題-“這個人沒有增值工作要做嗎?如果沒有,那麼這個人的工作對我們來說是必要的嗎?根本沒有?”

    甚至不要問是否可以進行這些修復,因為沒有問題可以解決,也沒有通過修復提供任何改進。

    對於執行的消息呈現給最終用戶/客戶,一定要標識他們進行修復,讓更高的人知道您已看到它,並提出對其進行更正。當然,這類基本錯誤並不能很好地反映在公司中,因此修復這些錯誤確實可以增加實質性價值。

    這樣做的好處是拼寫錯誤和語法錯誤使文檔更難以閱讀。提高內部文檔的可讀性是好的。
    @MartinBonner-OP將其描述為“簡單的拼寫錯誤,錯別字和不正確的語法”,並且對它們的理解足夠好,可以進行更正,因此,顯然它們一點也不難閱讀。如果我給這種感覺而不是更正確的“輸入此句”,那麼沒有人會因為將“ i”更改為“ y”,將“ a”更改為“ e”而頓悟。OP並不是在談論胡言亂語,只是清理一開始就完全可以理解的內容。我會小心翼翼地把它弄對,或者在看到它的情況下糾正自己的工作。我看不到這項工作的價值。
    我不是在說“有頓悟”,而是在說我能讀多快。可以理解“如果我付小費”,但這需要更多的努力。減少精力是值得的。
    @MartinBonner-我想,如果您認為需要“努力”,那麼我們將不得不不同意。
    這就是我來這裡的答案。您不應該花時間在非面向用戶的文檔中解決語法/拼寫問題。我以前做過當時我覺得自己很有生產力,但老實說我應該一直在從事該產品的開發。好的指導原則是僅在文檔無法按原樣使用或您已經在使用產品或進行重構時觸摸該文件時,才花時間來修復此類問題。


    該問答將自動從英語翻譯而來。原始內容可在stackexchange上找到,我們感謝它分發的cc by-sa 3.0許可。
    Loading...