Question

I have an issue that I feel many programmers can relate to…

I have worked on many small scale projects. After my initial paper brain storm I tend to start coding. What I come up with is usually a rough working model of the actual application. I design in a disconnected fashion so I am talking about underlying code libraries, user interfaces are the last thing as the library usually dictates what is needed in the UI. As my projects get bigger I worry that so should my “spec” or design document.

The above paragraph, from my investigations, is echoed all across the internet in one fashion or another. When a UI is concerned there is a bit more information but it is UI specific and does not relate to code libraries. What I am beginning to realise is that maybe code is code is code. It seems from my extensive research that there is no 1:1 mapping between a design document and the code.

When I need to research a topic I dump information into OneNote and from there I prioritise features into versions and then into related chunks so that development runs in a fairly linear fashion, my tasks tend to look like so:

1. Implement Binary File Reader
2. Implement Binary File Writer
3. Create Object to encapsulate Data for expression to the caller

Now any programmer worth his salt is aware that between those three to do items could be a potential wall of code that could expand out to multiple files. I have tried to map the complete code process for each task but I simply don’t think it can be done effectively. By the time one mangles pseudo code it is essentially code anyway so the time investment is negated.

So my question is this:

Am I right in assuming that the best documentation is the code itself. We are all in agreement that a high level overview is needed. How high should this be? Do you design to statement, class or concept level? What works for you?

Answer 1

In the end I found that there are a few ways to approach this, from mind maps to concept diagrams and even UML/Pseudo Code. In the end, what ever works best for the individual seems to be the thing to use.