Tuesday, November 13

Oopsla - Making Object-Orientation Work Better (David Lorge Parnas)

Its inspiring seeing David's presentation on this topic despite my personal opinion difference.

  • Object Orientation is a principle not an attribute of language (you can create non-OO program using OO language and vice versa)
  • Outdated documentation is worse than no-documentation at all
  • Program without documentation (documentation can be in many form) is not maintainable
  • Finish coding without writing documentation should not be considered complete


dbeilis said...

good point

I'm trying to think of documentation for agile process. I know that in one of the projects we used wiki to add agile dynamics to the documentation. How would you define a complete documentation? Do you know of any other approached besides wiki?

Nick Zhu said...

1. Well refactored and readable code is always the best form of living document, since they never go out of date.

2. Test cases are the best candidate for documenting usage of your code, since they are live demonstration of the usage naturally.

3. Code comments should only be used for documenting why not how since the code should be clear enough to express how directly.

4. High level architecture and domain model are the only ones that required separate documentation, since you can't capture that kind of concept directly from code, at least not very easily.