Tools and Philosophies for Understanding Large Projects

1
Tools and Philosophies for Understanding Large
Projects

• Michael Gaiman
• CS161
• November 28, 2005

2
Coding Large Projects for Understandability

• Literate Programming
• Design by Contract

3
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.

4
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.

5
Literate Tools

• WEB - 1984
• Knuths original tool, supports Pascal
• CWEB
• Knuth follow-up, supports C
• Noweb
• Simple, language independent literate tool
• Nuweb
• Language independent, seems to be more maintained

6
Literate Example
-- mode Noweb noweb-code-mode c-mode
-- \titleA 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 ltlthw.cppgtgt ltltheader filesgtgt ltltusing
directivesgtgt ltltmaingtgt _at_ The crux of the
application is the main function which simple
prints out the words Hello World and
returns. ltltmaingtgt
7
Literate Example (cont.)
int main(int argc, char argv) coutltltHello
Worldltltendl return 0 _at_ Next well discuss
the C scaffolding. In hello world, all we
need is the library for output ltltheader
filesgtgt include ltiostreamgt _at_ And as a standard
C file, Hello World uses the standard name
space. ltltusing directivesgtgt using namespace
std _at_
8
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.

9
Design by Contract (DBC)

• Specify interfaces by pre-conditions,
  post-conditions and invariants.
• Seeks to make explicit assumptions on which
  programmers rely when they write software
  elements that they believe are correct.

10
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

11
DBC Language Support

• Eiffel
• Object-Oriented originator of DBC.
• C
• Through pre-processors
• Java
• Through JML (Java Modeling Language)

12
DBC Example
withdraw(sum INTEGER)is -- Withdraw sum from
the account. require sum gt 0 sum lt balance
minimum_balance do add(sum) ensure
balance old balance sum end
13
Understanding Existing Large Projects

• If the project uses Literate Programming, then
  youre all set.
• If not, then
• Tools!

14
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

15
Tags Example

• Global on Python 2.4.2

global main Demo/embed/demo.c Modules/ccpyth
on.cc Modules/python.c Parser/pgenmain.c global
PyMain Modules/main.c
16
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

17
Source-Navigator
18
References

• Literate Programming http//www.literateprogrammi
  ng.com/
• Design By Contract http//en.wikipedia.org/wiki/D
  esign_by_contract
• Eiffel http//en.wikipedia.org/wiki/Eiffel_progra
  mming_language
• Global http//www.gnu.org/software/global
• Source-Navigator http//sourcenav.sourceforge.net
  /