Is there a well known way to document the process done before writting any code?

Question

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.

The Question

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.

Answer 1

What you are looking for is the requirement specification document.

This document usually has two chapters:

1. the clients expectations about the software to write and
2. a description of the Systems Architecture

This (two?) document(s) should be placed in the same SCM as your code (yes, a documents folder is a good place) in a format that SCMs can handle easily (markdown, HTML, LaTeX).

The reason is that requirements tend to change during development time, especially in an "agile" project and then you might want to explore when a requirement changed: before or after the code not meeting the new requirement was written.

Answer 2

In your example use case, it seems you're more interested in integration testing rather than requirements testing. However, the rest of your question concerns the process of discovering requirements. I will try to explain a bit about that process, and what tools you might be able to use for expanding the requirements to fully cover what is expected of the system.

The actual discovery process is more a procedural affair. As in most things in life, any tool you choose to use is there to support the software development process you're using to create your application. (examples of SDCLs are: Scrum, Kanban, Waterfall and RUP) The process mostly what you make of it. It's up to you to revisit the spec and update it if necessary. The process you choose will determine what is the best tool for the job.

There's a big problem with fixing things up front: they do not allow for much flexibility and therefore will (needlessly?) increase design complexity, which in turn will probably increase the errors in code and design. The more you are unwilling to revisit past decisions and the products of those decisions, the more painfull the development process will be in terms of quality assurance and often also customer satisfaction and timely delivery. (that's basically the big lesson of agile methodologies)

That being said, there are some tools to help you along by documenting requirements:

One way to document requirements is to write specification tests. These tests allow domain experts to specify situations in natural language and then code-literate people can attach tests to these scenarios. Specflow is an example of a system which can do this for you in C#

Another way is to use rigid specification standards. An example of this is IEEE 830

Neither fixes the interface of the application. If you're prepared to fix the interface, at least at a high level, then you can also write unit tests and link them to your requirements in your ALM software (like you can do in TFS)

Besides the requirements you can also use meta languages like UML to help you take design decisions and document these. The ubiquitous class diagram is infamous for oversimplifying things, yes remains one of the most common ways of displaying code structure.

There's pros and cons to using such a language. You're going to pull design more to the front of the development cycle, and make it less flexible. On the other hand, you will get a chance to work on the concepts more and get a better idea of what you're doing. If used properly, with more than just the class diagram, UML can be helpful to establish a rough outline of code structure and processes.

Answer 3

It sounds to me like you're talking about Architectural Decision Records.