What I Want to do
I'm in a process of sketching, prototyping and brainstorming to know the possibilities the code will deal with and what kind of problems I could face while writing the code. And decide how the code must behave to face the problem that solves, evaluating pros and cons of possible behaviours.
What I Know About
In github I saw a lot of code that documents functions with a description and explain how the code behaves and discussions aim to make the code behaving better, but never saw documentation of what leaded to decide the "aim" of a code.
So the question is, where to "publish" that content. In the comments of the not yet written code? In a separate txt? Under a Specific folder?. As the questions here requires to not generate a discussion but an specific answer, the specific question is if already exists a well known and studied way to do this, or something like what I'm doing. JUST how and where Document plans, not how planning.
An Example of What I've Done
What I'm doing is a memory manager, just like the one that has a operating system to allocate programs in memory while they are running, or sometimes kept there after close like a kind of cache.
Here I'm trying to figure out all the possible needs for memory to be allocated where you could allocate memory and delete it. By example it could have to deal with holes of unused memory between used sections of memory (If in the final design that will be allowed). Anyway in this list there are no decisions taken, just trying to describe the scenario, to clarify thigs a bit.
Data and objects in memory by behavior: ------------------------------------- (#.Category) ([letter]-Condition. Implicances) ------------------------------------- 1.Initialization: A-It is declared in the beginning. 4A B-It is declared on the run. 2.Persistency: A-It is needed for several operations. B-It is needed for just one operation. 3Ba 3.Deletion: A-Lasts forever. B-Could be deleted. a-Will be deleted. 4.Ammount of data: A-There is a fixed known ammount of data to be stored. B-The ammount of data to be stored is unknown while storing until finished.
The list below is a mock-up of decisions taken by defining distinct object types with a specific behavior to later assign a way to treat them.
Objects to store: Type A: Description: There is certainty that they will be used and never need be deleted enlarged or srinked. Type B: Description: They are not intended to exist forever and it is not certain that they will be needed to be deleted. Type C: Description: They are known to be deleted or exist just for a short time but there could be other operations while this object exists. Auxiliary Memory: Description: There is no certainty of how many data will be needed to store. A space where data can be stored and used within ONE operation, once used must NOT be leaved there to read later, so it can be safely overwritten or deleted. Anyway the data written here can be reclaimed to be marked as an object to prevent being overwritten/deleted.