Software Engineering Workshop, December 5-6, 2005 Jan Beutel
Transcript of Software Engineering Workshop, December 5-6, 2005 Jan Beutel
December 5, 2005
Documentation and Project Organization
Software Engineering Workshop,December 5-6, 2005
Jan Beutel
ETH Zürich, Institut TIK
2
OverviewProject Organization
SpecificationBug tracking/MilestonesAccess to information – mail, web, files, version control
DocumentationUser Guides, SpecificationsInline doc’s – commented code, automated doc’sREADME vs. ChangeLogMailing listsStructure – overview documents
ExamplesDo’s and don’ts in a university environment/sada
3
Project Organization – Different MeansPlain text documentsMS ProjectFile serverMailing listsWeb pages
Authored/StaticWikis
Repositoriessourceforge.netsavannah.nongnu.orgBSCW
4
Single DocumentsPlain Text
The ultimate LT-interfaceEasy to generate and readUniversalEasy to automate with shell scripts, Perl, Java, etc. Require lot’s of discipline (formatting, location, versions, debugging)
File Server StorageEasy to use, fastOffline sync works with Windows, CVS, SVN or gnu syncNot universally accessibleNot maintenance free (human intervention necessary)Permission Problems
5
MS Project et. al.Industry standard for large projects
Integrate resource/personnel planningBased on tool availabilityRevision control?
Good means for planning/trackingMilestonesSubprojectsResources/personnel
Extensive reporting capabilitiesAutomated checksExporting to html
Bit of an overkill for most of us…
6
Email – Mailing ListsFast, universal, accessible
Mailing listsDifferent audiences use different lists (devel, user, core)Usually too much information to stay currentMailing lists usually come with archival functionOperation not maintenance free (access, spam, etc…)
Mailing lists – Searching the archivesLocal mail dir starts at subscription date and bloatsNo straightforward search through everything in archivesNot all lists are search(-ed/-able) by Google
7
Web PagesAuthored/Static pages
FastWho is the webmaster?
Wiki PagesEveryone is the webmaster!Hierarchical permissionsContinuous improvement of contentTransparent ChangeLogControl/accuracy of content?
8
Wiki Pages – www.btnode.ethz.ch
9
Wiki Pages – Simple Markup for Everyone
10
Wiki Pages – Integrated ChangeLog
11
Wiki Pages – History Compare
12
Wiki Pages – Access Control, Internal Page
13
Wiki Pages – iGEM Collaboration Success
14
Wiki Pages RevisitedProjects must have certain size/impactDB based Wikis require maintenanceEasy porting of static pages using script interfaces
Some doc’s still need static pagesAuto-generated content: weblogs, doxygen, …Downloads“Long-term” static links
15
Weblogs – Interesting Project Statistics
16
Project Specific Weblog in 5 minutesGrep through the access_log for “your” filesRun webalizer over this data
#/bin/shcd /foo_bar_dir/btnode_weblogrm -rf btnode_access.log
grep -h -i btnode /install_dir/apache/logs/access_log > /foo_bar_dir/btnode_weblog/btnode_access.log
webalizer -c ./webalizer.conf -Q
17
sourceforge.netSourceForge.net is the world's largest open source software development web site, hosting more than 100,000 projects and over 1,000,000 registered users with a centralized resource for managing projects, issues, communications, and code.
Free of cost
Hosting of many services:Web pages, release management, CVS, news, support, tracking facilities, stats, mailing lists, user management
Access/availability: Very good for developers, stable enough for public
18
SourceForge.net
19
SourceForge.net – Feature Requests
20
SourceForge.net - Tracker
21
BSCW RepositoriesBasic Support for Cooperative Work
Originates in very large, multinational projectsMany features, lots of maintenance, complicated usage
22
Software DocumentationSoftware Documentation or Source Code Documentation is written text that accompanies computer software. It either explains how it operates or how to use it. [wikipedia.org]
Types of documentation:Architecture - Architectural overview of software; including relations to an environment, construction principles to be used in design and technical documentation, etc.Design - The design of software components.Technical - Documentation of code, algorithms, interfaces, APIs.End User - Manuals for the end-user.Operator - Manuals for the systems administrator.Application operator - Manuals for the "superuser" of the software.Help desk - Manuals for first and second line support.
23
Software Documentation cont.Often, tools such as Doxygen, javadoc, ROBODoc, POD or TwinText can be used to auto-generate the code documents; that is they extract the comments from the source code and create reference manuals in such forms as text or HTML files. Code documents are often organized into a reference guide style, allowing a programmer to quickly look up an arbitrary function or class.
Many programmers really like the idea of auto-generating documentation for various reasons. For example, because it is extracted from the source code itself (for example, through comments), the programmer can write it while referring to his code, and can use the same tools he used to create the source code, to make the documentation. This makes it much easier to keep the documentation up-to-date.
Of course, a downside is that only programmers can edit this kind of documentation, and it depends on them to refresh the output (for example, by running a cron job to update the documents nightly). Some would characterize this as a pro rather than a con.
Donald Knuth has insisted on the fact that software documentation can be a very difficult afterthought process and has been advocating Literate programmingwhere documentation is written in the same time as the source code andextracted by automatic means.
24
Industry Documentation Flows
25
Useful Documentation TypesUser GuidesSpecification DocumentsInline doc’s – comments, automated doc’sREADME vs. ChangeLogMailing listsStructure – overview documents
Examples
26
User GuidesEngineers tend to ignore these
We usually unpack, plug-in, start up and have troubles…
Usually contain interesting detailsBasic overviewRelease NotesConfiguration information
Large effort to create and maintain
27
Specifications
28
TinyOS TEP ConventionsGeneral Conventions============================================================
- Avoid the use of acronyms and abbreviations that are not well known. Try not to abbreviate "just because".
- Acronyms should be capitalized (as in Java), i.e., Adc, not ADC. Exception: 2-letter acronyms should be all caps (e.g., AM for active messages, not Am)
- If you need to abbreviate a word, do so consistently. Try to be consistent with code outside your own.
- All code should be documented using `nesdoc` [nesdoc]_, `Doxygen` [Doxygen]_ or `Javadoc` [Javadoc]_. Ideally each command, event and function has documentation. At a bare minimum the interface, component, class or file needs a paragraph of description. - If you write code for a file, add an `@author` tag to the toplevel documentation block.
29
TinyOS – TEP Structure
30
DoxygenDoxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, ...HTML, Latex, RTF and XML outputSimple configuration files and wizardsSimple, versatile markup:
31
Doxygen Overview Output
32
Doxygen – Simple Document MarkupDescribe every function
Add additional informationParametersUsageContextData types
Separate overview doc’s
Single configuration file
33
Doxygen - File References
34
Doxygen – File Reference and Examples
35
Doxygen – Simple Centralized Descriptions
36
Project ChangeLogTHE document to stayup-to-date
Easy to implement
Easy to maintain
Usage and disciplinemust be strictly enforced
37
Maintained ChangeLogs in Source Files
38
Handcrafted Comments and Version Info
39
Handcrafted CommentsOften necessary to understand application contextMust be used with careQuality control is hard
Who wrote it?When?Why?Is it still current?What was the exact case…
Often not cleaned up, lacking maintenanceCan be pretty ‘private”
40
Handcrafted Comments – The Good & Bad
41
Structure and Overview Doc’s
42
Worthwhile – TutorialsDon’t really work unless moderated or someone is exceptionally motivated…
43
Maintenance Intensive - FAQs
44
Documentation and Organization –Typical Problems
People from different groups – departments –schools – companies – countries – …
No common infrastructure availableAccess hierarchies (internal, external)
Most projects follow an “explorative” pathYou organize as you goNot much long term planning
Different people join at different times…All information must be archived and accessible
Public visibilityMust be organized, structured and cleanWill lead to questions (and workload)
45
Do’s and Don’tsUniversity: environments, responsibilities, project membership and working styles change frequently
People come and go fastNew/young people start from scratch every 3-4 yearsNo corporate policies on resources/doc’s
Do notSet up complicated/maintenance intensive systemsDo not rely on information to be pushed at you
46
Undergrad Student ProjectsEnforce discipline
Weekly meetings or status updates (email)
This is exceptional!
47
Undergrad Student ProjectsEnforce discipline
Weekly meetings or status updates (email)Interactive preparation of milestonesUse of version controlReading and posting to mailing lists (very hard)
Do not rely on quality/results of student projects to meet project/paper deadlines
SA projects are dry runs, time is shortSAs usually provide a good proof of concept.Technical documentation usually goodContext, scrutinizing questions, numerical analysis often lacking in precision/depth