Documentation?
A reader writes in response to Think First, Please:
Not to be rude or impertinent, or seemingly ignorant of how development works In Real Life, but don’t you have documentation of your interfaces to avoid this sort of thing?
It’s a good question.
It would be nice, but no, we probably don’t have the interface documentation being asked about. We have documentation, but in this case the code in question is considered a prototype brought into an application for refactoring.
Generally speaking, on our team prototypes aren’t documented much, unless they are fairly large or complex subsystems in which the engineer may write up a paper or presentation to describe the design. In this instance the prototype was a small subsystem, so we didn’t have a lot of documentation on hand but we did have some, although the engineer still could have used a little forethought on the task.
To explain more, most documentation we have involves high-level and conceptual documentation to describe the overall system. Class level documentation is written as Doxygen comments directly in the code, but that includes descriptions and class interfaces. We’re working on a fairly fluid project in that prototyping and feature iteration is a regular occurrence.
Also, our development practice does not focus on well-defined interfaces up front. We do, however, focus on concrete design principles. Some would say we risk bloated interfaces, which is possible, but we have yet to deal with such an issue because our design principles prevent it from happening. I’m a strong believer in design principles over design documentation.
Plus, there’s the teamwork aspect. We are very collaborative, have daily 15 minute meetings, and communicate throughout the day. We’re a small team so this works for us (6 software and some artists). It wouldn’t work for a large team, which would probably need that interface documentation more than we do.
Filed under: Process
