22

Some people have this problem that they cannot think without words. And writing down their thoughts and decisions is the most effective way to proceed.

So - is it normal and acceptable that I write down my thoughts and decisions in some Notepad++ file during coding?

Sometimes it should be acceptable, e.g. when recreating technical documentation or reasoning about more complex algorithms, but sometimes it may be strange, e.g. when I am considering design options and trying to make judgment.

The impact of this practice on productivity is unclear. From the one side - reasoning with inner words may be faster than with the written words. From the other side - more complex problems requires writing. Besides, if one is stuck with more design options, then the feeling is better when the decision is written, so it rises morale.

Improve this question
14
  • 5
    I tend to do this as well, and generally regret it when I don't. It's really helpful to have something to look back on later to remember why you did something a certain way, or to be able to make a decision later when you're not elbow deep in it with tunnel vision. When I forget to note something down I usually forget why, and then spend more time retracing my steps.
    – PseudoPsyche
    Aug 26, 2016 at 21:36
  • 21
    I feel like we are missing part of the context? Was this observation made around a complaint around efficiency? Often, criticism comes with suggestion for root cause which may or may not be relevant.
    – Jim Rush
    Aug 26, 2016 at 21:36
  • 9
    "Comments and documentation" needs to be written down into the source code and kept. Your thoughts about considering design options might be written down, but typically not kept, that is stuff that will seldom help you later (you may keep notes about the results of that thought process, if it is not clear from the source code itself, but that is not what you asked about). If you prefer an electronic form, a pencil-and-paper-form, or if you can do this all in your head, is up to you, noone else but you can tell you what works best for you.
    – Doc Brown
    Aug 26, 2016 at 21:46
  • 4
    ... P.S: I typically prefer pencil and paper, or a white board for this stuff, and I think I would not become a better programmer if I would try to do this all in my head, quite the opposite.
    – Doc Brown
    Aug 26, 2016 at 21:50
  • 7
    Why wouldn’t it be acceptable? Acceptable to who?
    – Paul D. Waite
    Aug 27, 2016 at 14:37

9 Answers 9

Reset to default
61

Not only is it normal, it's a good idea.

There's a famous quote

"Give me six hours to chop down a tree and I will spend the first four sharpening the axe".

Taking the time to organize your thoughts and plan your work before coding is time well spent. Putting those thoughts on paper will give you time to reflect on your plans, critique them, and organize them in ways that would be very difficult if done only "in your head".

Improve this answer
3
  • 8
    It's a good quote, though I'd remove the erroneous attribution. quoteinvestigator.com/tag/abraham-lincoln
    – Paul Draper
    Aug 27, 2016 at 17:37
  • 1
    Surely a true statement and good quote, but to my understanding the question has a different focus. As far as I understand it, the OP has no doubts about the importance of planning beforehand. He is asking if it is more efficient to write these thoughts/planning down, or just to keep them all only in his head.
    – Doc Brown
    Aug 27, 2016 at 22:54
  • 2
    Reckon an hour of sharpening is more than sufficient. This task should have been estimated at 3 hours max, but the slack has been spent on pointless over-preparation. What was the moral again? ;-)
    – Steve Jessop
    Aug 28, 2016 at 17:15
26

Yes, this is perfectly acceptable and normal.

Documenting your decision-making process is often valuable when revisiting code, to help determine why code was written in a certain way.

These notes can be included directly in the code as comments, if short enough. Extended commentary is often kept as part of an external technical design document.

Improve this answer
7
  • 4
    I would heavily recommend not to include notes about considering design options and trying to make judgment as comments in the source code, these are never "short enough". Only the final results of that thought process, but that is quite different from what the OP was asking.
    – Doc Brown
    Aug 26, 2016 at 21:53
  • 3
    I often find myself in discussions along the lines of "why did we make this decision." It's incredibly helpful to go back to my daily project notes to provide context, including the alternatives we discussed. I think I'm in good company: according to The Everything Store Jeff Bezos does the same.
    – kdgregory
    Aug 26, 2016 at 22:31
  • 8
    @DocBrown - sometimes it is a good idea to include reasons why you did not use other possible methods/algorithms so a future developer won't try to replace what you've done
    – HorusKol
    Aug 26, 2016 at 22:56
  • 1
    @HorusKol: sure, in some rare cases, that is trivial common sense. But that is quite different from "documenting the decision-making process".
    – Doc Brown
    Aug 26, 2016 at 23:59
  • 1
    @DocBrown right, I don't think anyone wants pages of notes in their source code. :)
    – mcknz
    Aug 27, 2016 at 2:24
20

It's a damn good idea. Right up until it becomes a way to procrastinate.

The key is balance. I find I'm most productive if I don't box my self in but capture ideas as they come.

If I'm grinding at a low level and a high level idea comes I just jot it down and come back to it later.

Planning out work is a good idea but unless you have to communicate or present before an audience the best tools are pen and napkin. Capture the idea. Don't waste time making it pretty.

Improve this answer
2
  • Markdown is another great way to take these notes. Keeps your hands on the keyboard, so there's minimal disruption to the thought process.
    – RubberDuck
    Aug 27, 2016 at 0:27
  • 1
    Whether firing up an editor or grabbing a pen and napkin is the better alternative is entirely up to your personal touch-typing and hand-writing skills. For me, the better solution clearly is the editor.
    – cmaster - reinstate monica
    Aug 27, 2016 at 9:14
9

In any professional situation, it's not only "normal and acceptable", it's mandatory. The typical development cycle consists of two documentation phases before any coding even begins:

  1. Functional Requirements Document: typically written by business analysts, specifying the functionality to be implemented.

  2. Detail Design Document: which is pretty much what you're talking about, just more formal, specifying the functional decomposition (factoring) of the system, algorithms, etc. Some of my (very) old ones are online, e.g. this.

For less formal documentation, I 110% agree with preceding remarks about inline comments. That's the only way to go; one way or another, everything else eventually gets lost. But neat and thoughtful inline commenting is a separate coding skill, developed through effort and practice like any other skill. You can see some of my (very) old stuff at, e.g. this. That style may or may not appeal to you. I'd recommend first finding some well-commented code with a style you like, and emulating that in your own code. After a while, adapt it as you see fit.

Improve this answer
4

A great place to put this kind of information is directly in the commit message of your version control system (SVN, git, etc). This way you can see the changes and the reasoning for them in the same place.

Improve this answer
4
  • 1
    It also makes them searchable. You can search commit messages in commandline git and sourcetree eg.. If you just use notepad, most likely the files never gonna be opened again and are hard to search without knowing some extensive bash and writing a script that searches all the relevant places.
    – HopefullyHelpful
    Aug 27, 2016 at 16:26
  • I try to do this in both my commit statements as well as the bug or feature request with links to the commit. I also do dated inline comments in the code with reasons why I changed the code. This helps dramatically in our creaky old code base where comments are largely unknown.
    – delliottg
    Aug 27, 2016 at 17:46
  • No, this is something else. Commit messages should describe what was done, not why. The why goes in your documenting code comments, accompanying documentation and issue tracker resolution. You can't put five pages of notes and design work in a commit message, nor should you want to.
    – Lightness Races in Orbit
    Aug 28, 2016 at 12:44
  • It is great to put it in the version control system. A better place is a plain text file inside though. Those are easier to use than commit messages.
    – Thorbjørn Ravn Andersen
    Aug 28, 2016 at 16:18
2

In addition to the other good answers, I'll add that I often write down my thoughts about what I'm trying to do.

Being very explicit about articulating what I'm trying to do helps me realize presumptions, assumptions and/or requirements that don't necessarily hold.

That then hints at alternatives, which I can then mull over better each in turn; that writing helping save my place if I think of something else.

I take quick notes to explore breath and depth, so it works recursively, helping me elaborate, navigate, and evaluate a solution tree, backing up, exploring, discovering, realizing, and deciding.

Improve this answer
1

Writing down anything that can save you/(new)teammembers time is time well spend. Just make sure it's something that someone might need later and don't overthink unless it's a real longterm project.

It also shouldn't take any time whatsoever. If you spend time thinking you can write your thoughts down 1 to 1 (as long as they will/can be useful to someone).

The real problem could be overthinking what you write. Just because you are writing doesn't mean you have to adhere to some already existing format or need to go all the way of creating a full documentation.

If your choice is between not writing down anything and just writing unformal notes on a notepad, then just write unformal notes.

Improve this answer
1

You say: "Some people have this problem that they cannot think without words. And writing down their thoughts and decisions is the most effective way to proceed."

If writing down your thoughts and decisions is the most effective way to proceed, why would it not be normal and acceptable to proceed in the most effective way? You do what works best for you. It may not be what works best for someone else. In that case you don't let someone else tell you what is best for you, and you don't tell them what is best for them. Everyone does what is best for them.

Improve this answer
1

Humans can only hold around seven "things" in their head at once. That's the reason for seven-digit phone numbers. In order for programmers to work efficiently they have to find some sort of system to offload things from their memory and quickly retrieve it later as needed. Your taking notes is an obvious and direct way, but everyone working on anything moderately complex has to do it somehow. When you pair program with someone, make a point to look for their method.

One common way is test driven development. In this methodology, you write one failing test, you write just enough code to get that failing test to pass, then you refactor your code to make it look nicer while keeping all your existing tests passing. This methodology keeps all your "notes" encoded inside the tests. People can work very rapidly this way without seeming to take notes, because they are just focused on the next test.

Another common way is to just write your notes in your code as pseudocode comments or stubs, then gradually substitute it with the real thing. This is how I usually write algorithms. My first draft is just a main function with pseudocode, then gradually it fills out into deeper and deeper levels of abstraction.

Don't feel bad about using whatever method works for you, but try to notice what methods your "efficient" colleagues are using. They have the same human limitations you do.

Improve this answer
1
  • 1
    TDD is a note-taking exercise? I don't think so.
    – Robert Harvey
    Aug 28, 2016 at 18:05

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