您現在的位置是:電腦技術吧?>? 基礎知識 ??>??程序是由程序員編寫的,程序是程序員編寫的??>??正文詳情

程序是由程序員編寫的,程序是程序員編寫的

竇盼秋2019-12-18 10:02:30 人圍觀
簡介程序員嗎為什么要記錄?你將在六個月內使用你的代碼。我覺得首先從個人利益的角度來解釋這個問題很有吸引力。最好的記錄理由是你將在六個月內使用你的代碼。您六個月前編寫的

  為什么要寫文檔?  你將會在 6 個月后使用你的代碼  我發現一開始從利己的角度來解釋這個問題會比較有吸引力。

寫文檔最好的理由就是你將會在 6 個月后使用你的代碼。

你 6 個月前寫的代碼跟別人寫的代碼對你來說通常沒有什么區別。

你將會帶著一種熟悉的感覺讀你的代碼。

然后一種不良的預兆悄悄逼近,你發現寫代碼的人毫無經驗,毫無智慧。

  當你讀完幾個月前很簡單易懂或者取巧的代碼之后,你就會開始同情你的用戶。

只要我寫下為什么我要這么做,生活就會變得如此簡單。

文檔能讓你記錄代碼為什么這樣寫的原因。

同樣地,代碼注釋解釋了為什么,而不是怎么做,文檔也是這樣。

  你想要別人使用你的代碼  你已經寫了一段代碼,并且發布了它。

你這樣做是因為你認為別人可能覺得它有用。

但是,人們需要先知道為什么你的代碼對他們可能有用,才會決定使用它。

文檔可以告訴人們這個項目對他們有用。

  如果人們不知道你項目存在的意義,他們不會使用它。

  如果人們不知道怎么安裝你的程序,他們不會使用它。

  如果人們不知道怎么使用你的代碼,他們不會使用它。

  只有少數人會深入研究你的代碼并且使用它。

幾乎沒人會使用你的代碼,除非它有好的文檔。

如果你真的熱愛你的項目,給它寫文檔,讓其他人使用它。

  你需要別人的幫助  開源項目是具有魔力的,對嗎?你發布了代碼,然后 code gnomes 出現并且讓你的代碼更好。

  當你發布代碼的時候會有一種奇妙的感覺產生。

它通過各種方式出現,但總是能讓你興奮不已。

有人在使用我的代碼?這是一種混合了恐懼和興奮的感覺。

  我創造了價值!  如果它出錯了怎么辦?!  我是一個開源項目開發者了!  天哪,別人在使用我的代碼。

  寫好的文檔能夠減輕這種恐懼。

很多恐懼來自于給世界創造東西。

我最喜歡的關于這個問題的引文如下所示:  恐懼來自于你做著重要的事情。

  如果你在做不讓你恐懼的事情,那么它對你或者世界都沒有益處。

  恭喜你感到恐懼!它意味著你在做重要的事情。

  實際上,不完全是這樣。

  開源項目確實令人感到驚奇,但它同樣必須符合現實世界的規則。

你必須有付出,才有收獲。

  在你為項目付出大量工作之后,才能獲得貢獻。

  在你的項目有用戶之后,才能獲得貢獻。

  在你的項目有文檔之后,才能獲得貢獻。

  文檔也為你項目的第一次貢獻提供平臺。

很多人從來沒有為開源項目貢獻過,讓他們修改代碼比修改文檔可怕得多。

如果你沒有文檔,你將失去這類文檔貢獻者。

  文檔讓你的代碼更好  有一個古老的事實:把東西寫下來幫助你更好地思考。

頭腦里產生一個聽起來不錯的想法很容易,但是把想法寫到紙上就需要思想上的升華。

  寫文檔能提升代碼的設計。

在紙上討論你的API和設計決定可以讓你用一種更正式的方式思考它們。

它還有一個不錯的副作用:讓別人按照你原來的意圖貢獻代碼。

  你想成為一個更好的寫作者。

  寫文檔跟大多數人體驗過的寫作方式不同。

技術寫作是一種非與生俱來的藝術。

寫文檔將會是你成為更好的技術寫作者這條路的起點,作為程序員,這是一個有用的技能。

  寫作會隨著時間的流逝變得更容易。

如果你好幾個月沒寫東西,再次動筆就會變得更加困難。

邊做項目邊寫文檔將會讓你保持一個合理寫作節奏。

  用什么工具寫作  簡單的開始是取得實際成果的最好方式。

我將會提供一條平坦的路給你走,在你有了基本的想法之后,你可以擴大范圍。

這些工具很強大并且容易使用。

這將移除寫作的障礙。

  這篇文章中的例子在 Markdown 和 reStructuredText 中都是有效的。

reStructuredText 有一點難用,但是更強大。

我推薦你兩個都看看,然后決定哪個你想要用。

  純文本版本控制  做為程序員我們生活中純文本的世界里。

我們的文檔工具不應例外。

我們想要能把純文本轉化成漂亮的 HTML 的工具。

我們還有一些最好的跟蹤文件變化的工具。

為什么我們寫文檔的時候會放棄使用這些工具?這套工作流是強大的,并且對開發者來說很熟悉的。

  基本例子  Resources  ---------  * Online documentation: http://docs.writethedocs.org/  * Conference: http://conf.writethedocs.org/  上面的文字將渲染成標題,下面帶著列表。

URLs 將會被自動超鏈接。

這寫起來很容易,不但作為純文本有意義,而且還能很好的渲染成 HTML。

  README  你第一個應該寫的文檔是 README。

如果你提供了合適的擴展名,代碼托管服務會自動把你的 README 渲染成 HTML。

它也是大多數用戶跟你的項目的第一次互動。

所以,一個可靠的 README 對你的項目十分有用。

  有些人甚至 從 README 開始做項目。

  文檔寫什么  現在我們來討論重要的事情。

確保你的用戶能得到他們需要的所有信息,但不要太多。

  首先,你需要問自己:文檔是為誰而寫。

一開始,你只需要吸引兩類的讀者:  用戶  開發者  用戶是指那些只是想使用你的代碼,而不管關心它怎么工作的人。

開發者是指那些想要給你的代碼做貢獻的人。

  你的項目解決了哪些問題  很多人會通過你的文檔搞清楚你的項目是什么。

有人會提到它,有人會隨機地用 Google 搜索一個短語。

你應該解釋你的項目做了什么和它存在的意義。

Fabric 這方面做的很好。

  一個代碼的小例子  提供一個生動的例子來告知用戶你的項目通常會被用來做什么。

Requests 是一個很好的例子。

  一個代碼和問題追蹤的鏈接  人們有時候喜歡瀏覽源代碼。

他們可能對歸檔他們發現的代碼 BUG 感興趣。

盡可能地讓那些想要為項目做貢獻的人做這件事很容易。

我認為 Python Guide 做得很好,因為它有指向代碼部分的鏈接。

  常見問題(FAQ)  很多人會有相同的問題。

如果問題一直發生,你應該適當地修改你的文檔或者代碼來解決問題。

但是總是有一些經常被問的關于項目的問題,不能改變的的事情等。

把這些記錄在文檔中,并且使其保持最新。

FAQs 通常會過時,但當它們被很好的維護時,它們就是黃金資源。

Tastypie 做得很好,它把 FAQs 整理成Cookbook。

  如何獲取支持  郵件列表?IRC 頻道?文檔要記錄如何獲取幫助和跟項目社區交流。

Django 這方面做得很好。

  給貢獻者的信息  在項目中,人們通常有怎么做事情的標準。

你應該記錄在文檔上,以便于別人寫代碼時能符合項目的標準。

Open Comparison 這方面做的很好。

  安裝說明  一旦人們決定使用你的代碼,他們需要知道如何獲取它和運行它。

但愿你的安裝指令只有幾行用于基本使用。

如果有必要,給出提供更多信息和說明的頁面鏈接。

我認為 Read the Docs 中我們做得很好。

  你的項目許可證  BSD?MIT? GPL? 這些證書可能對你來說沒什么,但是使用你代碼的人會很關心這個。

考慮一下你想要用什么證書發布你的項目,務必選擇一個互聯網上的標準許可證。

  下一步做什么  在你遵循上面的指南之后,我們相信你的項目將會成功。

進一步的參考資料,查看這篇文章 如何維護一個開源項目。

  模板  給你一個 README 的模板。

如果你使用 markdown 的語法,把它命名為 README.md。

如果你使用 reStructuredText 的語法,把它命名為 README.rst。

  $project  ========  $project will solve your problem of where to start with documentation,  by providing a basic explanation of how to do it easily.  Look how easy it is to use:  import project  # Get your stuff done  project.do_stuff()  Features  --------  - Be awesome  - Make things faster  Installation  ------------  Install $project by running:  install project  Contribute  ----------  - Issue Tracker: github.com/$project/$project/issues  - Source Code: github.com/$project/$project  Support  -------  If you are having issues, please let us know.  We have a mailing list located at: [email protected]  License  -------  The project is licensed under the BSD license.

版權聲明:本文由 竇盼秋 整理編輯。

原標題:程序員 碼農,程序員和碼農

轉載注明出處:http://www.dn9ww09s.icu/basics/15525.html

文章評論

    共有條評論來說兩句吧...

    用戶名:

    驗證碼:

作者推薦

  • android橫向滑動,excel滑動條橫向太長

    android橫向滑動,excel滑動條橫向太長 相關圖片表格怎么設置上下滑動本文主要介紹在Android中實現水平滑動(horizontallsliding)listview的實例。本文采用控件自身封裝的方法來解決這一需求。您可以參考A在表格中滑動條橫向怎么去掉...

  • 宏數據庫,數據庫中的宏

    宏數據庫,數據庫中的宏 相關圖片含有宏的數據庫如果有許多宏,將它們分組到不同的宏組中可以幫助方便地管理數據庫。創建表單并添加4個按鈕(如果出現“按鈕向導”對話框,請選擇“取消”)。根據創建宏的方法...

  • oracle數據庫常用命令,Oracle PlSQL常用命令

    oracle數據庫常用命令,Oracle PlSQL常用命令 相關圖片oracle命令大全1)檢查集群狀態:[[email protected]~]$crsctl check cluster crs-4537:cluster readyservices is onoracle基本命令...

  • 項目優化是什么,項目優化分析

    項目優化是什么,項目優化分析 相關圖片流程優化方案本文演示如何合并和壓縮基于requirejs的項目。在本文中,我將使用一些艱苦的工具,包括node.js。所以如果你手頭沒有node.js,你可以在這里下載一個多目標優化...

  • C內核開發,IDEA可以開發C號碼

    C內核開發,IDEA可以開發C號碼 相關圖片linux系統下C開發一。Cocoapods是一個運行在ruby中的軟件,可能需要幾分鐘才能安裝。安裝名稱是sudo gem install cocopods 2。如果要為每個第三方開源C開發工具...

  • 有愛插件字符串,防騎WA插件字符串

    有愛插件字符串,防騎WA插件字符串 相關圖片wa字符串導入不進去本文主要介紹了亞音速3.0插件更新字符串過長引起的異常修復方法。對于您的朋友,請參考公司客服最近提交的一個bug。更新產品詳細信息時,其中一些無法更新。他...

  • jsp多選框,jsp中接收多選框數組

    jsp多選框,jsp中接收多選框數組 相關圖片jsp復選框代碼在struts 1項目中,JSP頁面的多選框內容被轉移到下一頁。當涉及到修改表信息(或用戶信息)時,很難在一開始就知道如何實踐這個函數,很多JS代碼都是為了勉強jsp怎么獲...

  • 數據庫存取錯誤,java存取數據庫的包

    數據庫存取錯誤,java存取數據庫的包 相關圖片數據庫特點ADO訪問數據庫時是否顯示頁面?如果你目前已經在很多網站上使用過電子公告板程序,你應該知道,為了提高頁面的閱讀速度,電子公告板程序一般不會把所有的帖子都列在...

  • ip數據庫有什么用,連接數據庫IP

    ip數據庫有什么用,連接數據庫IP 相關圖片mysql數據庫ip地址本文主要介紹Python訪問純IP數據庫腳本共享,本文直接給出了實現代碼,可以參考以下項目的需要,通過IP地址來確定客戶端是Netcom還是電信。我從我的同事那sql數據庫...

  • 常見編程術語,編程專業術語

    常見編程術語,編程專業術語 相關圖片計算機編程中常用的術語php什么意思?很多行外人看這三個會毫無頭緒完全不知道php是什么,本文小編就為大家詳細介紹一下php的含義,帶來編程術語php百科解釋。  php什么意思?編什么...

熱評文章

  • php讀取文件夾,php文件夾

    php讀取文件夾,php文件夾 相關圖片php讀取文件函數本文的例子描述了PHP從文件夾中隨機讀取文件的方法。與您分享以供參考。具體實現方法如下:?12345678910131415161718192021222325php讀取空間指定文件夾內容...

  • 數據怎么存入數據庫,文件存入數據庫

    數據怎么存入數據庫,文件存入數據庫 相關圖片數據庫可以存數組嗎用ASP編寫網站應用程序需要很長時間,不可避免地會產生各種問題。恐怕最常見的問題是如何上傳文件到服務器,尤其是上傳圖片。比如,如果你想在自己的社區實...

  • object獲取值,獲取textbox的值

    object獲取值,獲取textbox的值 相關圖片textarea怎么獲取值本文主要介紹如何獲取DataRow[]的值。您可以引用DataRow[]Dr=DT。Select(T1=a');結果是一個數組,您只需要循環該數組。代碼如下:Sjs獲取標簽的值...

  • pyramid scheme,schemes什么意思

    pyramid scheme,schemes什么意思 相關圖片qq音樂url schemes在IOS應用程序中,經常可以看到一些應用程序通過單擊操作直接跳轉到app store頁面。首先,奇怪的是,這個第三方應用程序是如何在IOS系統應用程序交互中實現url schemes 微...

  • 電腦用戶鎖定怎么解除,用戶已被鎖定

    電腦用戶鎖定怎么解除,用戶已被鎖定 相關圖片華為賬號鎖定怎么解除甲骨文解鎖Scott/Tiger用戶。一。為Scott用戶驗證當前系統的狀態:從DBA中選擇*[users where upper(username)='Scowin10賬戶鎖定多久解除...

  • javascript提交表單,js自動提交表單

    javascript提交表單,js自動提交表單 相關圖片form表單提交多條數據本文主要介紹了對JSON格式表單數據提交相關資料的深入分析。供您參考的是,以JSON編碼格式提交表單數據是HTML5對web發展和演進的又一貢獻。以前,我們的Hajax提交...

  • 排序命令,excel命令

    排序命令,excel命令 相關圖片對于excel數據庫排序是按照我確信您對redis sort命令了解不多,所以我編譯了一些redissort命令的使用方法和示例,希望這些示例能對您有所幫助。Redis sort是Redislinux按時間排序...

  • sqlserver數據庫字段說明,sqlserver數據庫增加字段

    sqlserver數據庫字段說明,sqlserver數據庫增加字段 相關圖片sqlserver數據庫特點有時我們想知道這個值來自哪個表和字段,搜索Internet,找到更好的方法,并通過存儲過程實現它。只要傳入一個要查找的值,就可以找到該值所在的表和字段名。前提...

  • 在編譯時if怎么用,編譯時注解

    在編譯時if怎么用,編譯時注解 相關圖片編譯注解和運行時注解本文主要介紹PHP編譯安裝中常見錯誤的解決方法。本文介紹了PHP編譯和安裝中的大多數錯誤,并提供了解決方案。對于你的朋友,請參考這篇文章是在https://co編譯...

  • 自定義壁紙 文字,手機壁紙自定義文字

    自定義壁紙 文字,手機壁紙自定義文字 相關圖片照片加文字本文給出了一個Android實現的文本圖片自定義按鈕的實例。與您分享以供參考。具體分析如下:在Android開發中,經常需要使用帶有文本和圖片的按鈕。讓我們解釋美圖秀秀怎么...

關注微信

变脸官网查询