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.

TomR
  • 1,003
  • 1
  • 9
  • 17
  • 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 '16 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 '16 at 21:36
  • 1
    It is you who is working, you can do whatever you think works best for you. – Doc Brown Aug 26 '16 at 21:38
  • I have worked with far more productive developers than I am and I wonder how they were able to write code without comments and documentation. Of course I don't know whether they created some "personal" documentation, but I guess - no. So, maybe one have to learn to think without writing... – TomR Aug 26 '16 at 21:39
  • I'd guess "yes" - they did create personal documentation. Unfortunately some of that doesn't translate well into comments or documentation fit for others to read. – Dan Pichelman Aug 26 '16 at 21:40
  • 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 '16 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 '16 at 21:50
  • 3
    @DocBrown I disagree about not keeping those notes. I can't count how many times I *wished* I knew why someone decided on one design over another. And that includes some past version of myself. Recording architectural decisions for posterity is a wise thing to do. Not just the outcome, but other options considered and why we chose the one we did. – RubberDuck Aug 27 '16 at 00:24
  • 1
    @RubberDuck: for comments, graphics, notes within the decision making process one will typically need one or more pages or scetches. For documenting the result of that process, one will need typically only a few words, a sentence or two. The OP is IMHO clearly is talking about the first kind of stuff, not the second. – Doc Brown Aug 27 '16 at 08:22
  • 7
    Why wouldn’t it be acceptable? Acceptable to who? – Paul D. Waite Aug 27 '16 at 14:37
  • 1
    After 40+ years in the industry, I've met a (very) few _natural_ developers. I don't recall any who did as you describe unless they also were interested in writing articles/books. There are differences between 'talent' and 'skill'. It's not the same for a 'skilled' developer who might use your technique as a method to further 'skill' proficiency. It's certainly "acceptable" if it works for you. Only wide surveys could help decide if it's "normal". It seems not to be "abnormal". – user2338816 Aug 28 '16 at 00:03
  • 1
    I'm not sure this fits what you're saying exactly, but when I find myself really rolling, ideas get flowing so quickly that I'm just fighting to get the most complex details out and roughly frame the rest... allthewhile thinking of different options\errors\ways to do things that I'll want to account for later. To keep up, I started to leave myself quick temp. notes in the code so I can go back later, see what I was thinking, and finish. I usually start lines with *** and no indent (perhaps in comment) to find them later. Sort of pseudocode hiding in the code. Not sure this if this is typical? – JeopardyTempest Aug 28 '16 at 06:54
  • This would be a great start on the documentation to accompany the finished code. Especially the "Why?" questions seems to be easily answerable with this. – Thorbjørn Ravn Andersen Aug 28 '16 at 16:17
  • 1
    I don't know if this is what you mean, but I have to write down any thought that isn't arbitrary, in order to move on to the next thought. I don't regard it has documentation has many here seem to think, I throw it out as soon as I don't need to think about it any more, often at the end of the day. I can't tell you if it is normal or accepted, but I can tell you that you aren't alone. :) (I use a notebook and pen though) – Chris Wohlert Aug 28 '16 at 16:39

9 Answers9

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".

Dan Pichelman
  • 13,773
  • 8
  • 42
  • 73
  • 8
    It's a good quote, though I'd remove the erroneous attribution. http://quoteinvestigator.com/tag/abraham-lincoln – Paul Draper Aug 27 '16 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 '16 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 '16 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.

mcknz
  • 903
  • 7
  • 17
  • It is good to know that this practice can be formalized and the result adapted for later reuse for other developers. – TomR Aug 26 '16 at 21:35
  • 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 '16 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](https://www.amazon.com/dp/0316219282) Jeff Bezos does the same. – kdgregory Aug 26 '16 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 '16 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 '16 at 23:59
  • 1
    @DocBrown right, I don't think anyone wants pages of notes in their source code. :) – mcknz Aug 27 '16 at 02:24
  • 1
    No need to document the decision making process. But often there is an alternative with obvious advantages - and not so obvious disadvantages - that was rejected. If you don't write down those disadvantages then everyone reading the code will want to change it to the alternative method with its obvious advantages. – gnasher729 Aug 27 '16 at 23:32
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.

candied_orange
  • 102,279
  • 24
  • 197
  • 315
  • 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 '16 at 00: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 '16 at 09: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.

user
  • 449
  • 1
  • 5
  • 20
John Forkosh
  • 821
  • 5
  • 11
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.

Derek
  • 174
  • 5
  • 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 '16 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 '16 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 '16 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 '16 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.

Erik Eidt
  • 33,282
  • 5
  • 57
  • 91
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.

HopefullyHelpful
  • 229
  • 2
  • 8
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.

gnasher729
  • 42,090
  • 4
  • 59
  • 119
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.

Karl Bielefeldt
  • 146,727
  • 38
  • 279
  • 479