楊珂　雷開彬　楊玉涵

摘要：文檔是軟件產(chǎn)品的重要組成部分，但在目前的軟件工程教學(xué)中，對學(xué)生文檔能力的培養(yǎng)仍然欠缺有效的方法。文章首先分析學(xué)生文檔能力不足的原因，在此基礎(chǔ)上提出對學(xué)生文檔能力培養(yǎng)的基本要求，探索在項目教學(xué)法中著重培養(yǎng)學(xué)生文檔能力的教學(xué)新方法和新思路，總結(jié)能夠提高學(xué)生文檔能力的有效方法和技巧。

關(guān)鍵詞：文檔能力；軟件工程；課程設(shè)計；軟件創(chuàng)新；項目驅(qū)動

0、引言

目前，軟件工程課程教學(xué)中普遍存在著重代碼、輕文檔的現(xiàn)象，而在實際的軟件工程開發(fā)實踐中，一般認為代碼的工作量只占整個工程工作量的30%左右，而相關(guān)的完整、有效的各種文檔，包括設(shè)計文檔、算法文檔、說明文檔、維護文檔等才是整個軟件工程的核心所在。為了加深學(xué)生對軟件文檔的正確認識，培養(yǎng)學(xué)生軟件文檔的編寫和審核能力，增強學(xué)生的軟件工程能力，我們必須轉(zhuǎn)變教學(xué)觀念，在教學(xué)過程的各個環(huán)節(jié)中突出文檔的重要地位，強調(diào)設(shè)計對于軟件的正面作用，將各種統(tǒng)一、標準、高效和實用的文檔設(shè)計和撰寫方案融入課程教學(xué)中，并且與軟件工程理論和代碼編寫結(jié)合，形成完整的理論、算法、代碼和文檔并重的教學(xué)新方法。

1、文檔能力的重要性及現(xiàn)狀

軟件產(chǎn)品被定義為包括程序、數(shù)據(jù)及其相關(guān)文檔的完整集合。由此可見，文檔是軟件產(chǎn)品中不可或缺的重要組成部分。作為軟件工程過程中的重要里程碑和有效的交流工具，文檔不僅能夠幫助開發(fā)人員掌握自己的工作進度，方便團隊中的所有成員理解和改進代碼，還能幫助項目管理人員對軟件開發(fā)進程進行有效控制和管理，進而提高軟件開發(fā)的效率和質(zhì)量，改進軟件開發(fā)過程。

在目前實際的課程教學(xué)中，雖然引入了案例教學(xué)、校企合作等方法，也結(jié)合了國內(nèi)外一些有效的軟件工程教學(xué)方法，但實際教學(xué)效果卻遠遠跟不上現(xiàn)實中軟件行業(yè)的實際需要。通過調(diào)查發(fā)現(xiàn)，大部分學(xué)生并不能理解文檔在軟件工程中的重要地位，不知如何編制規(guī)范有效的文檔，如何使用和管理文檔。經(jīng)過了解、調(diào)查和分析，造成這種現(xiàn)狀的原因主要有3個方面。

（1）在前兩年的專業(yè)基礎(chǔ)課學(xué)習(xí)中，所有程序都是經(jīng)過簡單設(shè)計后直接映射為程序，學(xué)生沒有接觸過軟件文檔，缺乏對思維邏輯的條理性強化。

（2）高年級課程中的項目復(fù)雜性不高，學(xué)生無法意識到缺乏有效的文檔給項目帶來的深遠影響。教師雖然反復(fù)強調(diào)文檔的重要性，但由于學(xué)生的經(jīng)歷和經(jīng)驗有限，很難引起共鳴。

（3）軟件文檔本身的多樣性、復(fù)雜性和高質(zhì)量要求，使文檔編寫成為一項艱苦和枯燥的勞動過程，進一步加重了學(xué)生對軟件文檔無從下手和望而卻步的感受。

2、文檔能力培養(yǎng)的內(nèi)容和要求

我國于2006年發(fā)布了國家標準《計算機軟件文檔編制規(guī)范（GB/T 8567-2006）》（以下簡稱《規(guī)范》），作為軟件開發(fā)人員工作的準則和規(guī)程。鑒于計算機系統(tǒng)的多樣性，該標準一般不涉及整個系統(tǒng)開發(fā)中的文檔編制問題，而僅僅是軟件開發(fā)過程中的文檔編制指南。因此，考慮到教學(xué)適用的軟件項目復(fù)雜度以及學(xué)生的技術(shù)能力等限制因素，文中涉及的文檔能力僅以《規(guī)范》作為指導(dǎo)。軟件工程專業(yè)學(xué)生文檔能力包括文檔編寫能力、文檔審查和評審能力。

2.1 文檔編寫能力

軟件文檔的編寫是保證軟件質(zhì)量的重要措施，也是軟件維護的主要依據(jù)。因此，一定要注重培養(yǎng)學(xué)生的文檔編寫能力，使學(xué)生能夠嚴格按照軟件工程規(guī)范的要求，遵循常見軟件文檔的規(guī)范，充分利用常用的CASE工具，準確地描述用戶需求、設(shè)計思路與算法，結(jié)合文字、圖形等多種展現(xiàn)形式，形成規(guī)范性的文檔記錄。為了保證軟件文檔的質(zhì)量，根據(jù)《規(guī)范》，在培養(yǎng)學(xué)生文檔編寫能力的過程中，應(yīng)注意堅持以下幾點要求。

（1）針對性：在文檔編寫前應(yīng)注意區(qū)分不同文檔針對的讀者對象群體，根據(jù)不同類型、不同層次的讀者，編寫更適應(yīng)他們需要的文檔。

（2）文檔種類間內(nèi)容的重復(fù)性：不同種類的文檔內(nèi)容相互之間允許存在一定的重復(fù)，為了方便讀者，每種文檔應(yīng)該自成體系，盡量避免在讀一種文檔時必須參閱另一種文檔的現(xiàn)象。

（3）規(guī)范性：所有的文檔必須按照《規(guī)范》規(guī)定的內(nèi)容格式編寫，一般不得變動章節(jié)的標題和順序，各層次的條目可以根據(jù)實際需要細分、縮并或省略，新增加的條目應(yīng)加在原章節(jié)條目內(nèi)容的后面。

（4）精確性：文檔的描述應(yīng)該盡量準確，不能出現(xiàn)多義性的描述。另外，同一項目中幾種文檔需要重復(fù)的內(nèi)容應(yīng)該協(xié)調(diào)一致、沒有矛盾。

（5）完整性：任何一篇文檔都應(yīng)該是完整和獨立的，可以自成體系。

2.2 文檔審查和評審能力

階段評審是軟件工程過程中的重要組成部分。軟件生命周期中的各個階段，都應(yīng)該堅持嚴格的階段評審。由軟件文檔的重要性可知，文檔評審也是階段評審的重要工作內(nèi)容。因此，對學(xué)生文檔能力的培養(yǎng)，也體現(xiàn)在對學(xué)生文檔審查和評審能力的鍛煉和培養(yǎng)上，這可以加強學(xué)生對規(guī)范性文檔標準的認識和理解，進一步提升學(xué)生的文檔編寫能力。文檔審查和評審能力的培養(yǎng)主要要求學(xué)生能對自己或者他人撰寫的軟件文檔，從文檔結(jié)構(gòu)的規(guī)范性和合理性、文檔內(nèi)容的完整性和一致性、語言表述的準確性等角度進行分析和判斷，并作出合理化的建議性描述。

3、文檔能力培養(yǎng)實踐

軟件文檔是軟件產(chǎn)品的重要組成部分，也緊密依托于軟件產(chǎn)品，要培養(yǎng)學(xué)生的文檔能力，必須在項目任務(wù)中加以鍛煉。為此，我們把對學(xué)生文檔能力的培養(yǎng)融入項目開發(fā)與管理的整個過程中，以項目為導(dǎo)向，以實踐為驅(qū)動，強調(diào)文檔在軟件整個生命周期中的地位和作用，堅持文檔的規(guī)范性、全面性和準確性要求，堅持嚴格的階段性評審和復(fù)審，培養(yǎng)學(xué)生重視文檔、編寫文檔和審查文檔的綜合能力，主要從幾方面對軟件工程教學(xué)作出改革和創(chuàng)新的嘗試。

3.1 搭建開放的工程實踐環(huán)境

實踐環(huán)境是保證實驗教學(xué)和質(zhì)量的基本條件，對于軟件工程課程顯得尤為重要。項目開發(fā)不是簡單的程序設(shè)計，而是軟件工程全過程的綜合性實踐，應(yīng)該建立和配置相應(yīng)的軟件工程實驗環(huán)境或?qū)嶒炛行摹Ｍ瑫r，就軟件工程而言，它關(guān)注的是大型程序的構(gòu)造，強調(diào)團隊合作。就學(xué)生的認識而言，糾正軟件開發(fā)的個人英雄主義和單兵作戰(zhàn)的錯誤思想極其重要，因此這就要求必須有一個支持團隊協(xié)作、數(shù)據(jù)共享的信息平臺。endprint

西南民族大學(xué)計算機科學(xué)與技術(shù)學(xué)院于2011年8月創(chuàng)建了學(xué)生軟件創(chuàng)新基地?；貙嶒炛行呐渲糜袑ｉT的文檔服務(wù)器，搭建了軟件協(xié)作開發(fā)與管理平臺，學(xué)生在這里擁有良好的軟件開發(fā)和團隊合作環(huán)境?；靥峁┝艘粋€開放式的工程實踐平臺，希望得到進一步學(xué)習(xí)和實踐鍛煉的學(xué)生可以自愿加入這個團隊，由專門的指導(dǎo)教師根據(jù)學(xué)生的特點和技術(shù)特長進行分組，組織和指導(dǎo)學(xué)生進行軟件項目的開發(fā)實踐。

3.2 教學(xué)環(huán)節(jié)的改革與實踐

在教學(xué)環(huán)節(jié)上，我們也必須對軟件工程課程的教學(xué)體系進行工程化改造，以便逐步建立工程化實踐教學(xué)體系，著力培養(yǎng)學(xué)生的工程化開發(fā)能力和職業(yè)素質(zhì)，進而形成一個將理論基礎(chǔ)、實驗教學(xué)、工程實踐融為一體的整體化培養(yǎng)機制。同時，必須把文檔的重要性及早在學(xué)生的意識觀念中建立起來，避免“重代碼、輕文檔”的錯誤觀念先入為主，并在隨后的教學(xué)中繼續(xù)逐步提升學(xué)生的文檔能力。

3.2.1 C語言課程設(shè)計

c語言課程設(shè)計是計算機科學(xué)與技術(shù)學(xué)院從2008年上學(xué)期開始新開設(shè)的一門專業(yè)選修課，目的是進一步增強學(xué)生的實際動手編程能力，逐步培養(yǎng)并提升學(xué)生的邏輯思維能力。

作為大一上學(xué)期程序設(shè)計課程的延續(xù)，該課程不僅強調(diào)學(xué)生對C語言中基本語法的掌握程度和動手編寫代碼的能力，同時更加注重學(xué)生邏輯思維能力的提高以及對解決問題思路和方案的清晰描述。在講解疑難題目時，通過繪制流程圖或者列出輔助表格幫助學(xué)生把握規(guī)律和理清思路；在糾正學(xué)生程序中的錯誤時，不直接給出正確答案或告訴學(xué)生應(yīng)如何修改，而是先請學(xué)生講出自己的思路，再按照該思路梳理每個步驟間的邏輯關(guān)系和內(nèi)在聯(lián)系，引導(dǎo)學(xué)生重新審視自己的設(shè)計，找出其中的錯誤根源。

通過此過程，學(xué)生逐漸認識到語法和代碼只是一個程序中最基礎(chǔ)的部分，而算法和思路才是整個程序的靈魂，為今后重視前期設(shè)計做好鋪墊。同時，學(xué)生也開始逐步嘗試和學(xué)會使用算法流程圖等工具描述和記錄他們的解題思路，而這些工具也正是后期學(xué)生接觸到軟件工程課程甚至進行軟件項目開發(fā)實踐時用于完成設(shè)計和編寫文檔的利器。

從筆者5年來的教學(xué)歷史和教學(xué)經(jīng)驗看，大部分學(xué)生用4-6周時間就能在很大程度上對上學(xué)期所學(xué)的c語言基本語法加以鞏固，完成其中相對比較基礎(chǔ)的簡單計算題，后期則逐漸把學(xué)習(xí)重點轉(zhuǎn)移到知識擴展和能力提升上。C語言課程設(shè)計鞏固了學(xué)生的程序編寫能力，同時讓學(xué)生潛移默化地認識到程序設(shè)計并不僅僅是編寫代碼，為其今后正確認識軟件工程和培養(yǎng)其文檔編寫能力打下了良好的基礎(chǔ)。

3.2.2 軟件工程概論

軟件工程概論是一門重要的專業(yè)基礎(chǔ)課程，具有很強的理論性和實踐性，其教學(xué)目標是讓學(xué)生熟練掌握軟件開發(fā)的原理、技術(shù)和方法，具備獨立或合作完成軟件項目開發(fā)所需要的邏輯思維、溝通合作、表達寫作以及組織管理能力。然而，由于該課程內(nèi)容多，涵蓋面廣，并且包含了大量抽象的概念和原理，容易使學(xué)生感覺到枯燥乏味；另一方面，迫于課時壓力，教師在授課過程中往往會降低教學(xué)難度，將課堂講授的重點放在基本概念和原理上，沒有機會讓學(xué)生接觸到較為真實和復(fù)雜的項目。再加上很多學(xué)生長久以來持有軟件開發(fā)就是編寫代碼的錯誤觀點，輕視分析、設(shè)計、測試與管理，導(dǎo)致課程的教學(xué)目標很難達到。

從2010年起，計算機科學(xué)與技術(shù)學(xué)院為軟件工程概論課程增加22個上機課時，同時引入以項目為導(dǎo)向的軟件工程教學(xué)模式。一方面，在課堂講授上，教師結(jié)合實際案例和真實的開發(fā)經(jīng)驗和教訓(xùn)為學(xué)生講解抽象的概念和原理，便于學(xué)生接受。同時，根據(jù)學(xué)生的自愿選擇有指導(dǎo)性地將所有學(xué)生劃分為若干小組，每個小組獨立承擔(dān)一個項目。另一方面，教師根據(jù)教學(xué)需要劃分軟件開發(fā)的各個階段和相應(yīng)的階段任務(wù)，由各個小組內(nèi)部協(xié)調(diào)細分到每位組員。每個小組在協(xié)作完成該階段的任務(wù)后向教師提交階段性成果，由教師進行審查和記錄。

在項目驅(qū)動的特定教學(xué)環(huán)境中，學(xué)生在實際項目的驅(qū)動下，帶著問題學(xué)習(xí)理論和開發(fā)技術(shù)，在項目實踐中鍛煉思維能力、問題求解能力和處理復(fù)雜任務(wù)的能力。由于文檔貫穿于軟件開發(fā)的整個生命周期，學(xué)生在進行軟件開發(fā)的過程中，查閱了大量關(guān)于文檔編寫的資料，掌握了軟件文檔編寫的基本框架結(jié)構(gòu)和一些文檔輔助生成工具的使用技巧。教師在收到學(xué)生提交的文檔后，對文檔進行仔細審查并及時提出修改意見和建議，幫助學(xué)生提高文檔質(zhì)量。對于其中典型的和有代表f生的設(shè)計開發(fā)文檔，教師還可以組織全體學(xué)生在課堂上以講解——提問—答疑的形式一起進行討論和評審，既活躍了課堂氣氛，拉近了師生之間的距離，又加深了學(xué)生對于軟件工程過程的認識，提高了學(xué)生的文檔能力。

3.2.3 學(xué)生創(chuàng)新實踐

項目教學(xué)、案例驅(qū)動等新教學(xué)模式的引入，使學(xué)生通過課堂上的學(xué)習(xí)和項目上的體驗，真實地感受到軟件生命周期從需求采集、建模設(shè)計到最后軟件測試中的各個環(huán)節(jié)，幫助學(xué)生建立起對軟件工程過程的感性認識，增強學(xué)生的文檔能力，但同時我們也必須要認識到，學(xué)生通過課程學(xué)習(xí)和體驗到的相關(guān)知識，與他們畢業(yè)后即將從事實際行業(yè)的要求和規(guī)范之間，仍然存在著很大的差距。Nurkkala和Brandle對現(xiàn)行的軟件工程教育和行業(yè)內(nèi)的現(xiàn)狀進行了深入研究和對比分析，指出因為受到實際教學(xué)環(huán)節(jié)中各種因素的制約，適用于教學(xué)的虛擬項目和行業(yè)中的實際項目相比，差距主要體現(xiàn)在沒有真實產(chǎn)品、持續(xù)時間短、流動性高、復(fù)雜性低、缺乏維護和沒有實際客戶6個方面，而項目上的差異也最終導(dǎo)致了學(xué)生對軟件產(chǎn)品、軟件工程過程認識不足，并形成了輕視文檔，認為開發(fā)過程的結(jié)束就是整個軟件項目的終結(jié)等錯誤觀念。

學(xué)生軟件創(chuàng)新基地則部分克服了上述這些因受到教學(xué)安排等限制而導(dǎo)致的不足之處，因而也在一定程度上解決了教育現(xiàn)狀和行業(yè)要求嚴重脫節(jié)的問題。首先，因為學(xué)生軟件創(chuàng)新基地相對獨立于學(xué)校規(guī)定的教學(xué)環(huán)節(jié)安排，因此具有較長的持續(xù)時間，從學(xué)生的角度而言，學(xué)生可以根據(jù)自己的愛好、特長在教師指導(dǎo)下自愿加入或退出創(chuàng)新基地，有比較充分的時間參與項目實踐，提高文檔能力和項目管理能力；從項目的角度而言，因為不再受到學(xué)期、學(xué)年的限制，項目開發(fā)周期可以更長，甚至可以包含軟件的上線測試和運營維護等開發(fā)后續(xù)階段。其次，創(chuàng)新基地中的學(xué)生是跨年級的，已有實踐經(jīng)驗的學(xué)生和新加入的學(xué)生可以在基地中共存，甚至在同一項目組中一起承擔(dān)項目子任務(wù)。因此，人力資源相對穩(wěn)定，新舊人員可以平穩(wěn)過渡，學(xué)生通過討論、交流、文檔評審等互動活動，從實踐中體會項目開發(fā)、文檔撰寫過程，令經(jīng)驗得到積累、延續(xù)和不斷擴展。最后，由于人員穩(wěn)定性較強，技術(shù)、經(jīng)驗?zāi)軌虻玫椒e累，因此能夠完成項目的復(fù)雜度也可以適當?shù)刂饾u提升，而開發(fā)出來的軟件產(chǎn)品也可以進行維護。

學(xué)生在創(chuàng)新基地的工作和軟件工程概論課程基本類似，由于時間和人力資源更加充分，技術(shù)水平也有一定的積累，因此相應(yīng)的區(qū)別主要體現(xiàn)在兩個方面：①接觸的項目更加復(fù)雜和真實，有時甚至是來源于校外企業(yè)的真實項目，開發(fā)周期也更長；②階段評審尤其是文檔評審也更加嚴格，有時一篇文檔甚至要評審、修改、復(fù)審好幾次。在這樣的鍛煉中，學(xué)生對自己的要求也更加嚴格，對文檔的撰寫方法和技巧更加熟悉，對文檔的把握也更加準確。

4、文檔能力培養(yǎng)成果

近4年來，通過在教學(xué)改革過程中的不斷摸索和嘗試，結(jié)合以項目為導(dǎo)向的“講授——引導(dǎo)——項目演練——交流總結(jié)”教學(xué)模式，我們總結(jié)出一些培養(yǎng)學(xué)生文檔能力的教學(xué)經(jīng)驗和方法，并初步取得了一些成果。

（1）一部分學(xué)生尤其是創(chuàng)新基地學(xué)生的文檔能力得到顯著提高，這些學(xué)生對于文檔的結(jié)構(gòu)、內(nèi)容組織和安排、編寫技巧等已有較好的基礎(chǔ)，并且會使用一些常用的計算機輔助設(shè)計工具配合編寫文檔。

（2）到目前為止，創(chuàng)新基地的學(xué)生已完成校外企業(yè)級項目2個、自立項目3個，在2個開發(fā)項目過程中共產(chǎn)生大小40余篇軟件文檔，包括需求規(guī)格說明書、概要設(shè)計文檔、數(shù)據(jù)庫設(shè)計文檔、用戶手冊、現(xiàn)場安裝部署文檔等，其中包含10余篇基本符合企業(yè)規(guī)范的正式軟件文檔。

（3）創(chuàng)新基地中的部分學(xué)生通過近3年的訓(xùn)練，在就業(yè)后具有較高的文檔編制能力，對軟件工程也有較深入的認識，并且具備了分析和設(shè)計軟件的基本能力，得到了所在單位的肯定。

5、結(jié)語

文檔對于軟件工程的重要作用決定了對學(xué)生文檔能力的培養(yǎng)是軟件工程教學(xué)過程中一個非常重要的環(huán)節(jié)。一方面，教師要通過案例教學(xué)的方式讓學(xué)生意識到文檔的重要性，糾正“重代碼、輕文檔”的錯誤觀念；另一方面，要結(jié)合項目驅(qū)動的教學(xué)模式在項目中加強對學(xué)生文檔寫作能力、審核和評審能力的鍛煉和培養(yǎng)，幫助學(xué)生逐漸養(yǎng)成編制文檔、評審文檔、管理文檔和使用文檔的習(xí)慣，加深對軟件工程的理解和把握，提高軟件開發(fā)的綜合素質(zhì)和能力。endprint