Pre Project Documentation [closed]

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 4 years ago.

开发者_如何学Go Improve this 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?

---

I'd HIGHLY recommend reading Code Complete 2 for some excellent insight into these kinds of questions.

http://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670

---

I think what you want is a software requirements specification.

Coding all the stuff in a chaotic way is a wrong mode of do the job! What you need is to create a list of function/non-functional requirements to create a linked/related/child/parent relationship with the requirements of the UI and for the business actor create use case.

After this step you need to eventually manage all the design interface in UML or SPEUDO Code, but when you are formalized the requirements (for small project) the need to have UML is putt off.

For the documentation of the code you can use doxygen or javadoc approch where in short, you insert comment on the code and with a software all the doc is putted off in HTML/PDF.

With this way you are reached in sequence this stuff:

1 - software requirement
Now you have the complete overview of what is your software and maybe what functionality you software need with what constraints (technical/non-technical/time/business). And also user case to test the software in the last stage of the development life cycle.

2 - UML or PSEUDO CODE
An easy way to split your work to other colleague and a simple code overview of the code interface design.

3 - library documentation for other coders like you and all the benefits to dont waste too match time to write down all the doc at the end of the project!

my 2 cents.

google keywords: software engineering doxygen software development life cycle, CMMI, IEEE SRS (Software requirements specification).

---

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.