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:
  ([letter]-Condition. Implicances)
    A-It is declared in the beginning. 4A 
    B-It is declared on the run.
    A-It is needed for several operations.
    B-It is needed for just one operation. 3Ba
    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:
      There is certainty that they will be used and never need be deleted
      enlarged or srinked.
  Type B: 
      They are not intended to exist forever and it is not certain
      that they will be needed to be deleted.
  Type C:
      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:
      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.
  • Possible duplicate of What to plan before starting development on a project?
    – gnat
    Aug 30, 2017 at 7:36
  • There the question there is how to plan, here is how and where document what being planned. Aug 30, 2017 at 7:41
  • Depends entirely on your audience, but a good idea is to write a summary of the program that your manager or non-IT could read and understand the basics of what the program does. The sections that follow the summary go into further detail that would require you to have some technical understanding. Unfortunately I don't know what your program is supposed to do, so I can't go into further details.
    – Neil
    Aug 30, 2017 at 7:50
  • Anyway this "documentation" (if can be called like that) is intended to be read by me and other developers, is just to "plan" pure abstract implementation details. Aug 30, 2017 at 7:55
  • It sounds to me like you're talking about ADRs (Architectural Decision Records)
    – RubberDuck
    Aug 31, 2017 at 16:17

3 Answers 3


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

  • 1
    Link-only answers are still sub-optimal, even if they've already been discussed in the comments. It's not at all clear how this relates to the question being asked, even after perusing the link. Aug 31, 2017 at 21:48
  • @RobertHarvey it directly answered OP's question, even without the link. They just needed the right term to describe the concept. softwareengineering.stackexchange.com/questions/356510/…
    – RubberDuck
    Aug 31, 2017 at 22:01
  • 1
    Yes, I saw that comment; I even said so in my first comment here. You two guys aren't really respecting the other users here; you're talking amongst yourselves, and I applaud you both for finding a term I hadn't heard before, but you and the OP aren't the only visitors to this post. Perhaps this explains it better than I can. Aug 31, 2017 at 22:10
  • @RobertHarvey I understand the potential problems of short and link only answers, but OP seriously just needed the right term to search. Even if the link goes dead, the answer would be easily searchable and useful for future visitors. The "rules" are really just a bunch of guidelines. If we put the rules before actually helping each other then we have seriously lost our way here.
    – RubberDuck
    Aug 31, 2017 at 22:16
  • How do we explain to future posters with "name that thing" questions that we don't do that here, when we have users doing the opposite? Aug 31, 2017 at 22:18

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.

  • Or the number version of your document match to the current version of the application. And each document version is stored independantly.
    – Walfrat
    Aug 30, 2017 at 9:50
  • That could reduce the requirement - feature gap down to one release cycle... if it would work. But at least at my company updating document versions it not a priority task... Aug 30, 2017 at 13:48
  • 2
    I would call it a design document, not a requirements document. Aug 30, 2017 at 22:14
  • This (two?) document(s) should be placed in the same SCM so my project's manager, who knows nothing about SCMs should be up-to-date with these sort of tools and he also will have to be granted for checking out and commit changes into the SCM... I'm not sure if that's good. Functional and technical requirements, IMO, should be located in a document management system (DMS) or in the project's manager application (Redmine, Jira, etc).
    – Laiv
    Aug 31, 2017 at 15:37
  • @Laiv Your manager shouldn't be managing a IT team, them. It's okay for the manager to not be a pro coder, but at the bare minimum he should be able to use the tools of the team. A manager that doesn't know the trade is blind.
    – T. Sar
    Aug 31, 2017 at 16:20

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.