Tools and Philosophies for
Understanding Large Projects
Michael Gaiman
CS161
November 28, 2005
Coding Large Projects for
Understandability
• Literate Programming
• Design by Contract
Literate Programming
• Develop programs from perspective of a
report or prose.
• Code and Documentation are interspersed in
one source file.
• Information is written in an order suitable
for human viewing and comprehension
• Tools process files and make them
compilable.
Literate Programming
• Pros
– Creates highly readable, highly understandable
source code and documentation from one file.
– Leverages TeX knowledge
• Cons
– Requires TeX knowledge (usually)
– Source maintenance can be more tedious.
Literate Tools
• WEB - 1984
– Knuth’s original tool, supports Pascal
• CWEB
– Knuth follow-up, supports C
• Noweb
– Simple, language independent literate tool
• Nuweb
– Language independent, seems to be more maintained
Literate Example
% -*- mode: Noweb; noweb-code-mode: c++-mode -*\title{A Hello World Example!}
A traditional introduction to new languages, Hello World has long been a
slightly amusing tradition in Computer Science.
Hello World has the following structure:
<<hw.cpp>>=
<<header files>>
<<using directives>>
<<main>>
@
The crux of the application is the main function which simple prints out the
words ``Hello World’’ and returns.
<<main>>=
Literate Example (cont.)
int main(int argc, char* argv[]) {
cout<<“Hello World”<<endl;
return 0;
}
@
Next we’ll discuss the $C++$ scaffolding. In hello world, all we need is the
library for output:
<<header files>>=
#include <iostream>
@
And as a standard $C++$ file, Hello World uses the standard name space.
<<using directives>>=
using namespace std;
@
Semi-Literate Programming
• Documentation Generators
– JavaDoc
– Doxygen
• Allows documentation to be extracted from
source
• May or may not allow source code
reordering.
– Some argue that to be semi-literate ordering, at
the least, is required.
Design by Contract (DBC)
• Specify interfaces by pre-conditions, postconditions and invariants.
• Seeks to make explicit assumptions on
which programmers rely when they write
software elements that they believe are
correct.
Design by Contract
• Pros:
– Allows for more reliable software
– Allows contract violations (exceptions) to be quickly pinned
down
– Allows for descriptive documentation to be automatically
generated.
– Much of unit testing is done automatically by contracts.
• Cons:
– Depending on compile settings, this can incur run-time costs
– Conditions can require duplication of coding effort
DBC Language Support
• Eiffel
– Object-Oriented originator of DBC.
• C
– Through pre-processors
• Java
– Through JML (Java Modeling Language)
DBC Example
withdraw(sum: INTEGER)is
-- Withdraw sum from the account.
require
sum >= 0
sum <= balance – minimum_balance
do
add(–sum)
ensure
balance =old balance – sum
end
Understanding Existing Large
Projects
• If the project uses Literate Programming,
then you’re all set.
• If not, then…
– Tools!
Tag Systems
• Builds database of symbols used in project.
• Allows easy searching of references and
definitions.
• Often integrates into editor of choice.
• Tools:
–
–
–
–
cscope
etags
ctags
GNU Global
Tags Example
• Global on Python 2.4.2
$global main
Demo/embed/demo.c
…
Modules/ccpython.cc
Modules/python.c
Parser/pgenmain.c
$global PyMain
Modules/main.c
Visual Tools
• Quickly see relationships between functions
and between classes
• Tools:
– Scat - displays function call graphs for C
– Source-Navigator - IDE/Visualizer for many
languages
Source-Navigator
References
• Literate Programming:
http://www.literateprogramming.com/
• Design By Contract:
http://en.wikipedia.org/wiki/Design_by_contract
• Eiffel:
http://en.wikipedia.org/wiki/Eiffel_programming_
language
• Global: http://www.gnu.org/software/global
• Source-Navigator:
http://sourcenav.sourceforge.net/