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 • 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

6. 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>>=

7. 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; @

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 >= 0 sum <= balance – minimum_balance do add(–sum) ensure balance =old balance – sum end

13. Understanding Existing Large Projects • If the project uses Literate Programming, then you’re 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/ccpython.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.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/