
Ask HN: Coding notes – how do you do them? - osullivj
For years I kept my coding notes in spiral bound A4 and A5 notebooks. Handwritten notes are quick to create, but hard to search. So these days I make notes in a series of flat files I edit in Notepad++. The files will have design ideas, debugging tips like favourite windbg commands, notes on existing code, scraps of SQL, stack traces for critical pieces of code, test results and timings, HOWTO notes on build and config, URLs,
draft blogs and outline plans. Notepad++&#x27;s Find in Files is invaluable for navigating them. There was a thread last year on paper notes [1], but I&#x27;m wondering how folk keep soft copies of notes. Back in the late 80s
I used GrandView [2]. What new solutions are there for capturing and organizing coding notes? How do you do it?<p>[1] https:&#x2F;&#x2F;news.ycombinator.com&#x2F;item?id=11890742
[2] https:&#x2F;&#x2F;en.wikipedia.org&#x2F;wiki&#x2F;GrandView_(software)
======
vstuart
Here's what I do:

* keep my notes in a flat, plain-text "reference" file

* key items/entries prefaced/abbreviated with leading double underscores; e.g.

__bash

__grep

__birthdays

\+ anything else you want

* bash script ("ref.sh"):
    
    
        #!/bin/bash
    
        # https://stackoverflow.com/questions/7131670/make-bash-alias-that-takes-parameter
    
        grep  -i  -A10000  --color=always  __$1  /home/victoria/projects/shortcuts/reference  |  more
    

* ~/.bashrc alias:
    
    
        # ----------------------------------------------------------------------------
        # SEARCH MY 'REFERENCE' FILE:
    
        # search my Reference file for argument, tagged (prepended) with two leading underscores (e.g.: 'ref wget' finds '__wget'):
        alias ref='/mnt/Vancouver/Programming/scripts/ref.sh'
        alias ?='/mnt/Vancouver/Programming/scripts/ref.sh'
    
        # "free" (unlimited) grep search of my '/mnt/Vancouver/ .reference' file (e.g. 'ref rename' : i.e., not limited by double-underscore tag):
        alias refgrep='/mnt/Vancouver/Programming/scripts/refgrep.sh'
    

* Now, when I want to find a note quickly, I launch a terminal, search, then exit out (alias "qq") ;-)

* E.g.: $ ref grep

* Image (screenshot): [http://imgur.com/a/7WPtD](http://imgur.com/a/7WPtD)

~~~
vstuart
Oops -- I should have included my "refgrep.sh" bash script:

#!/bin/bash

# [https://stackoverflow.com/questions/7131670/make-bash-
alias-...](https://stackoverflow.com/questions/7131670/make-bash-alias-that-
takes-parameter)

grep -i -A10 --color=always $1 /home/victoria/projects/shortcuts/reference |
more

===========================

I should also have mentioned that with either script/alias {ref | refgrep},
partial strings are automatically searched. [I created/use the latter script
because sometimes I cannot remember all of my __<entries>.]

For example, if you have two or more placemarkers that are similar (__python |
__pythonpath), "ref py" will find the first one; "ref pythonp" will find the
the second one ... just extend the string to be more specific, as needed ...

"refgrep <string>" will find (the first occurrence) of that string, anywhere
in the "reference" file.

I use that "reference" file for everything that I might want to quickly find
(literally, seconds): programming; birthdays; phone numbers; prescriptions,
doctors, you-name-it.

Just pop open a terminal; search (ref <string>); read; quit terminal. :-D

------
pimterry
Obviously, I spent far too much time building my own cli tool to manage them
in nice simple text format:
[https://github.com/pimterry/notes](https://github.com/pimterry/notes).

Don't ask how I kept notes on the implementation process.

~~~
niceperson
How did you keep notes on the implementation process?

------
criddell
How do you deal with diagrams and sketches?

I have a directory called notes that has a bunch of separate text files. Now
I've been slowly adding Word files because often I want to include an
annotated screenshot.

I've often wished I could paste images into my source code. My editor would
generate something like:

    
    
      /*IMG: BASE64 (or some other image encoding) of the image */
    

I do ascii art in some places, but too often I have a comment that just says
"see flow.png in the documentation directory".

~~~
dhd415
If using Microsoft tools is an option for you, you might consider OneNote. I
almost chose it for my use, but wanted something lighter weight.

~~~
criddell
How is OneNote's OCR? I also use Evernote and it does a great job of
recognizing and indexing text on photos of whiteboards.

~~~
dhd415
I've heard that it's good, but I never tried it myself. I think OneNote is
free now, so I'm pretty sure you could try it without having to buy anything.

~~~
criddell
I just created two image files. One is a handwritten list of provinces in
Canada and the other is a screenshot of some text in an editor. I uploaded the
files to OneNote and Evernote. Both programs indexed the screenshot perfectly
but only Evernote can find text in the handwritten note.

You said you chose something lighter weight. What did you end up going with?
I've used Evernote for years but am unhappy with the direction the program has
gone. The new CEO seems to be refocusing on the core purpose (capturing and
remembering) and so I'm contemplating sticking around for a bit.

~~~
dhd415
Ah, that's an awfully nice search capability. I posted elsewhere in this
thread that I use SimpleNote. It's not perfect, but >95% of my note-taking
needs were text-only and SimpleNote was less hassle than Evernote.

------
r3bl
I have a "notes" repo that I'm editing using... well, mostly Atom, sometimes
nano.

I use Markdown for pretty much everything I write on my laptop, including
notes, so printing them is no issue when I need to so.

I usually go down the "one topic, one file" path, and add a table of content
on top (I have a command line tool that does that).

I push a portion of my notes to a public GitHub repo, and all of them in a
private Git repo. Random example of me learning Ruby syntax:
[https://github.com/aleksandar-
todorovic/notes/blob/master/21...](https://github.com/aleksandar-
todorovic/notes/blob/master/21_ruby_101.md)

~~~
disease
I really like the idea of having all my notes in a git repo. I currently have
them on Google Drive which is great for searching and accessing anywhere on
any device - but I hate the fact that I have no local copy available since
they are Google Docs which just store as a link basically. Yeah I know about
Google Takeout but if I go with a repo I'll basically always be fully synced
up locally while being synced on the server whenever I do a push.

------
Hates_
I use Quiver for my coding notes
[http://happenapps.com/#quiver](http://happenapps.com/#quiver)

~~~
brandonhall
I concur on Quiver. I've been using it for months and it picks up nicely where
Evernote lacks. I do wish it was a bit better in the usability department, but
it's a fine tool. Also, I don't think it's been updated since I bought it.

------
neurocroc
I make mind maps of what ever topic I am learning / researching.
([https://github.com/nikitavoloboev/my-notes-
mindmaps#github-i...](https://github.com/nikitavoloboev/my-notes-
mindmaps#github-is-not-all-about-code))

I then add it to to the main research
([https://my.mindnode.com/83qmKgoATj8TyKzprzsPfoirxa2g9WmFGx3x...](https://my.mindnode.com/83qmKgoATj8TyKzprzsPfoirxa2g9WmFGx3xpr1J))
mind map.

It's actually really easy to keep it up to date and it is very rewarding
knowing that I can share my knowledge with other people.

I also wrote about my approach about mind mapping here
([https://medium.com/@NikitaVoloboev/mind-map-
everything-d2767...](https://medium.com/@NikitaVoloboev/mind-map-
everything-d27670f70739#.vxtzupdw2)).

~~~
zazibar
Great insight, thanks for posting.

------
informatimago
Over the last 40 years, I've accumulated a 471 KB ~/notes.txt file.

Currently, it's vaguely structured using the emacs org-mode

And indeed, no database, nothing beats the speed and convenience of search
with any random editor search function (let alone emacs occurs command or
regexp search).

~~~
bit-shifter
Now that's something I'd love to see! Care to share?

------
nstart
Might I suggest paper notes again? The mental state we go into when jotting
things down on paper physically combined with the flexibility seems a shame to
have lost.

I agree on search which is why I keep a digital index I update every few days.
So even a year and a couple of notebooks later I search for something like
"notes sql" on evernote and will get back results like "book 4 page 13 sql
notes on sharding". I just need to dig book 4 out of my little plastic box I
keep my notebooks in and refer :)

~~~
criddell
Clearly, you're familiar with this:

[https://en.wikipedia.org/wiki/Fundamental_theorem_of_softwar...](https://en.wikipedia.org/wiki/Fundamental_theorem_of_software_engineering)

~~~
nstart
Maybe. But in a both humorous and serious sense, this isn't a question of
complexity being abstracted is it? It's simply transferring a solution to
another medium. If not for software I'd solve the indexing issue the same way
I would with paper. I'd have one paper that acts as an index across my books.
Instead of using paper though I'm using a digital medium. So is that a case of
abstraction?

------
Starwatcher2001
I use simple text files, one per project, and UltraEdit (with tabs set to 2
spaces for brevity as I go up and down my stack). UE allows lines to be
bookmarked, which works nicely for highlighting "to do" stuff. What is missing
is tagging, but a few choice words and "find" is usually sufficient.

Mmm... just noticed that when I make notes, I talk to myself in the plural!

eg:

###############################################################################################

Problem: SalesOrders table has 2,381 distinct SONum records, but 13,489
records. We've got AlienRef in SalesOrders, but the one from Oracle is per
SalesLine. Let's drop it from that table. Need to fix the trigger code and
SalesOrdersDeleted - done.

Problem: insert Now fails on "Cannot insert the value NULL into column
'LastActivityUser', table 'Zeno_Dev.dbo.SalesReleasesAudit'; column does not
allow nulls. INSERT fails." Fixed.

Problem: There's duplicate SOnums in SalesOrders. eg: '100242032'

    
    
      SoNum 100242032 has TWO deliverypoints
      The addresses are the same, because we've got TWO customer numbers with the same delivery point. Aggh.
      
        CustomerID  CustNum
          3338        721180000
          3550        721180015
    
      DeliveryPointID, CustomerRef, DeliveryPointNum
        13579             3338          S0015
        13814             3550          S0015
      
      When we create SalesOrders, we need to match on DeliveryPointNum AND CustomerRef !
      
      Fixed.

------
throwaway020217
emacs org-mode. Features:

\- Flat files, allowing diffs and fast searches

\- Built-in todo, calendar and punchclock workflows out of the box, right from
within your notes.

\- diagrams, attachments, links

\- syntax highlighting, and code blocks can be executed!

\- org-capture for special forms

I use emacs in both windows and linux. It is so worth the learning curve, and
org-mode is one of the easiest and most rewarding entry points to emacs - it's
how I started with emacs, and now I live in it.

[edit: spacing of bullets]

------
divbit
[https://github.com/divbit/grimoire](https://github.com/divbit/grimoire)

Example output pdf for sharing:

[http://docdro.id/QPKoLBh](http://docdro.id/QPKoLBh)

You can also style the notes by simply dropping a <style> some css element {
some css thing: some number } <style> at the top of the note, which can make
for decent good looking documents (on par with word etc if you are a css
wizard). Also it has built in spaced repetition studying thing, which (the
code is there, but I'm in the slow process of debugging it since I messed it
up when I moved the state to redux, so it will be back in the next few
commits).

You can copy/paste images to there, and write with markdown / latex, which is
why I wrote it, since I couldn't find anything that did all those things
conveniently.

------
rukuu001
Spiral-bound notebooks with yellow stickies to mark the important bits I need
to refer back to.

The stickies poke out a bit, which is where I put a little label to aid
searching.

edit: more info

~~~
superquest
All roads lead here, IMO!

------
fiftyacorn
I used to run notepad, then evernote. Then i started a blog - so now i just
post on that. If its of use to others - then great. Otherwise at least i know
where my notes are

[http://glenware.wordpress.com](http://glenware.wordpress.com)

------
aosaigh
I recently got an iPad Pro and pencil. It's stupidly expensive but along with
the app Notability[0] it's made taking notes, sketching ideas, recording audio
in meetings, mocking up ideas an absolute breeze. It's completely replaced the
A4 notepad that I carried with me previously for day-to-day notes.

For more technical notes, I use Quiver[1] on OSX for keeping track of research
topics, code snippets, walkthroughs and tutorials, guides etc.

[0]: [http://gingerlabs.com/](http://gingerlabs.com/) [1]:
[http://happenapps.com/](http://happenapps.com/)

~~~
vortec
Shame Quiver ain't available for iOS. Do you know a similar tool which is?

------
majewsky
I'm actually amazed that you write down so much. When I tried to use physical
notebooks, I only ever ended up creating todolists on them, and task tracking
tools like Trello or GitHub Projects turn out to be much more effective for
that purpose.

EDIT: There's one exception where I write notes from time to time: design
notes for hypothetical software. I still have a few text files from a few
years back somewhere in a Git repo, where I hypothesized about how my own
programming language might look. Rust has stolen most of my ideas, though. :)
(There was actually something vaguely similar to the borrow checker in there.)

------
dsiegel2275
OneNote works well for this use case. It syncs automatically across machines
and devices, easy to search, does well with cut and pasted content, handles
links, images, etc.

~~~
tehbeard
I liked onenote, and haven't tried the desktop app.

But the web app had an annoying habit of continually hiding the edit ribbon,
making it a chore to use for formatting notes.

------
cpbotha
I use emacs with org-mode (embedded syntax highlighted and executable source
code blocks FTW) and org-download, the latter for embedding screenshots.

Besides my daily lab journal (one org file per month), I have project-specific
org files also. This whole notes directory hierarchy is synced everywhere,
also to my Android phone where I sometimes use emacs with termux to access
these notes.

Searching is done using helm-projectile-ag, which is bound to `C-c p s s`

------
DictumMortuum
I have created my own tool that uses couchDB as a document store back-end,
because I like the way it has built-in replication.

I use a command-line tool to fill my local couchDB with notes and then just
use the gh-pages hosted site to view them / search them.

[https://github.com/DictumMortuum/dictum](https://github.com/DictumMortuum/dictum)

------
sova
It depends on what... my coding universe is largely Clojure based now and I
still have plenty of notebooks full of sketches, designs, ideas, short
writings, and diagrams. I saw someone designed a whiteboard that sticks onto
the back of the laptop (lid) and it looks like an excellent invention.

For all the time I've spent studying computational science, I'm actually very
content to be without technology. For instance: I have my most valuable code
on github, and as long as I know it's there I know there's no problem if I
lose my physical machine. The IP is worth more than the hardware.

However, I can't say the same about notes. I don't keep my notes or writings
anywhere on the "cloud." I don't think there's a solution that exists yet that
is up-to-snuff for me, but someone did post a site that was made to be notes-
for-long-into-the-future recently, perhaps someone with better remembering can
find it.

~~~
jamessb
> someone did post a site that was made to be notes-for-long-into-the-future
> recently, perhaps someone with better remembering can find it.

You might be referring to Standard Notes [0], which advertises itself as
having a focus on longevity. The discussion on HN [1] mentions many
alternatives that are based on plain text.

[0]: [https://standardnotes.org/](https://standardnotes.org/)

[1]:
[https://news.ycombinator.com/item?id=13421927](https://news.ycombinator.com/item?id=13421927)

~~~
sova
Thank you

------
rhlala
I use the same method as yours, i pick it from
[http://www.devdungeon.com/content/python-tutorial-
starting-y...](http://www.devdungeon.com/content/python-tutorial-starting-
your-cookbook) , i dont see the point in using git for it, but it is a nice
introduction

------
LordHeini
Just a piece of paper which goes to the bin when the project (or a part of it)
is done. All notes regarding the code go into comments which helps teammembers
as much as it helps me (I hope) . I don't remember the tool I used for notes
but it jut stopped using it a long time ago. It is just a waste of time in my
opinion. What do I need random sql or other code for? If it is part of a
project there is no need to duplicate it (if it is your software might suck).
And if it is some other project there is usually not much use for it anyways.
Maybe I am weird in that regard but usually I am just fine with a few doodles
on paper and proper documentation.

------
karmajunkie
I've recently become a big fan of disc-bound notebooks. Buy one, get the hole
punch for the brand, and a ream of high quality paper, and go to town. You can
print various linings on them (e.g. Graph paper) and the best part for me is
rearranging the pages in whatever order ends up making sense, or toss things
like a todo list that's all done.

I've tried solutions like org-mode but I just find thinking on a keyboard to
be entirely inadequate for some reason. I end up doing a lot of free-form
notes so that might be one reason why.

------
bobstaples
I've been using dokuwiki[0] for this for a while now and I am quite satisfied
with it. It allows simple markdown so you can add (internal and external)
links, images and code snippets. If I remember correctly it also saves
everything to simple folder structured text files so you will always be able
to revert back to that when you want to take it offline. [0]
[https://www.dokuwiki.org/dokuwiki#](https://www.dokuwiki.org/dokuwiki#)

------
secstate
Kinda surprised no one has mentioned TiddlyWiki yet ... truly the hackers
notebook :)

[http://tiddlywiki.com/](http://tiddlywiki.com/)

------
padelt
FreeMind on Mac and Windows. Open-source software. Topics (SW-dev, Ops,
Processes) nicely form a foldable tree. Storage is cleartext readable XML.
Nodes take formatted richtext if needed. Syncs nicely via Owncloud or Dropbox
or git. Has been with me for 10+ years. Downsides: Jumping through Java hoops
on MacOS. Copy&Paste prone to non-ASCII punctuation/whitespace. Not really
maintained and hosted on Sourceforge.

------
mark_l_watson
I use Markdown to keep random notes in a Dropbox folder. I also keep project
related notes with the digital assets for each project. For travel notes, I
use Google Keep. I used to use Evernote for random useful links and copies of
useful information, but I have been transitioning to Apple Notes (proprietary
format, but these are my least important notes).

------
jedikv
I just use both pen and paper & Simplenote and connect it to apps like Nv etc.
It's free (for now), open source (mostly?) and lets me sync across
desktop/laptop/mobile.

Also has a nice export tool which I can use should I need to migrate. One
downside is markdown is not supported on the mac version from some reason
(works on windows/mobile)

------
dhd415
I wanted a tool with some organizational and formatting capabilities and
built-in syncing, so I used EverNote up until the point that they limited the
number of devices that would work for unpaid plans. I have since switched to
SimpleNote. Both have reasonable search capabilities. Neither are perfect for
what I want, but both are adequate.

~~~
ctrlrsf
How do you handle screenshots with SimpleNote? Only reason I'm still using
Evernote.

~~~
dhd415
I don't have any screenshots or other images in my notes. If I needed one, I'd
probably upload to an image hosting site and put the URL in my note. That's
obviously not as good as embedding inline, but I haven't found anything that I
consider perfect, yet. I probably would have just upgraded to a paid Evernote
account if I hadn't found their client apps so buggy.

------
DTrejo
I love [http://notational.net/](http://notational.net/) and have been using it
for years and written >380,000 words. Make sure you 1) set a bring-to-front
hotkey (life-changing) 2) store as rtf files to e.g. dropbox. There's also
nvalt but I've never had cause to use it.

------
finniananderson
I use Classeur [1] to store all my notes in a folder. You can use markdown
which is really quick & easy which makes formatting much quicker. Can export
to PDF etc via PANDOC, control access and you can even link it to a blog
service.

[1] [https://app.classeur.io](https://app.classeur.io)

------
grigoryvp
VIM with custom wiki plugin and custom wiki syntax:
[https://github.com/grigoryvp/home](https://github.com/grigoryvp/home)
[https://snag.gy/3TxCt5.jpg](https://snag.gy/3TxCt5.jpg)

~~~
kzisme
I love VIM - does this wiki plugin compare to the emacs org mode? (I've heard
a lot about it but never used it)

~~~
grigoryvp
Nope, it provides only syntax highlight for my custom format, and wikiword
jumps

------
tarboreus
Org mode and never look back.

[http://orgmode.org/](http://orgmode.org/)

------
marknote
I use my own app MarkNote
([https://marknote.github.io](https://marknote.github.io)) to record these
kind of notes. It supports markdown, all notes sync into iCloud and shared
among all my devices. Really make note taking easy!

~~~
blueclothes
It is a good idea to store markdown in iCloud. Nice!

------
mixedCase
Markdown. Synced with megasync.

Occasionally use Dia diagrams for ideas that map better with such a graphical
representation (subsystem interaction and the interfaces of its boundaries).

Anything more temporary than that (AKA brain buffer) goes into a whiteboard or
a paper notebook.

------
EleventhSun
I use cherrytree, it's a tree-like set of notes
[http://www.giuspen.com/cherrytree/](http://www.giuspen.com/cherrytree/)

------
tmaly
For useful script or snippets, I always keep a simple .txt file.

For notes, I use something like Google Keep so I can type them out on my phone
when I am out. Once a month, I copy to a spiral bound sketchpad.

------
bryanlarsen
One good place for some types of notes is Stack Overflow. There's a certain
kind of thrill googling for something and finding your SO answer or question
prominently in the results.

------
kitsuac
I use a simple plaintext heirarchical format which is compatible with
checkvist.com, and wrote a Notepad++ plugin which syncs local copies with
checkvist. Revisions via Git.

------
cabalamat
I use my CatWiki wiki software
[https://github.com/cabalamat/catwiki](https://github.com/cabalamat/catwiki)

------
drwl
@OP have you tried creating a table of contents or a look up table to for your
hand written notes? Physical accesses should be near O(1)

------
sixonesixo
for a while i was using VIM to edit and git to store my notes. I had a script
that create a new file every day and push the old one to my git repo. But now
i'm using IA Writer to write and store my daily notes, markdown support is
quite handy and it seems more usable instead of vim+git.

~~~
osullivj
I use bitbucket for my private repos, and github for the public ones, and I do
a git add *.txt in the notes directory periodically.

------
amelius
How about sketching on a piece of paper, scanning it, and include the image in
the git repository?

------
fpgadude
zim desktop wiki since 2008. Works well with Dropbox.

------
follower
I've been interested in the topic of coding notes / project logs for a number
of years primarily due to the positive benefit I've gained from the habit.

Quite some time ago I created Labradoc
[http://labradoc.com/](http://labradoc.com/) to help make the process easier
for myself & others and make myself incredibly wealthy through SaaS. While the
latter has not happened, :) the site has still been super valuable for me:
[http://www.labradoc.com/i/follower](http://www.labradoc.com/i/follower) (I
started my journey by using a single-file wiki tool:
[http://code.rancidbacon.com/ProjectLogArduinoUSB](http://code.rancidbacon.com/ProjectLogArduinoUSB)
.)

It hasn't had any feature (or design :) ) upgrades for...about half a decade
and while there are many things I've thought of adding it serves my purposes
in its current state.

While the past couple of years has seen the development of "project log" sites
for hackers/developers the general note-taking approach seems less common.
Part of the reason being that I suspect most developers are inclined to just
build their own.

Here's an example of a completed project log:
[http://www.labradoc.com/i/follower/p/project-sms-text-
scroll...](http://www.labradoc.com/i/follower/p/project-sms-text-scroller)

In addition to "project" logs I also have "topic" notes (e.g.
[http://www.labradoc.com/i/follower/p/notes-web-
bluetooth](http://www.labradoc.com/i/follower/p/notes-web-bluetooth) &
[http://www.labradoc.com/i/follower/p/notes-react-
native](http://www.labradoc.com/i/follower/p/notes-react-native)) which tend
to be a collection of reference links and then chronological notes related to
my work on the topic.

Here's some links to other posts about this subject & site which may be of
interest:

* "Show HN: Side project this weekend? Start a Labradoc project log to keep track.": [https://news.ycombinator.com/item?id=2669425](https://news.ycombinator.com/item?id=2669425)

* [https://news.ycombinator.com/item?id=2914071](https://news.ycombinator.com/item?id=2914071)

* [https://news.ycombinator.com/item?id=4213311](https://news.ycombinator.com/item?id=4213311)

And other random comments on the topic I've made:

* "I've found a project log as a good way to get an idea out of my head too--or out of the tabs in my browser :) until I'm ready to get back to it."

* "I consider it a form of a "commit log for your day"..."

* "The single biggest thing that's helped me context switch between projects (or return to one) has been keeping a project log. To me, a project log is to documentation as Twitter is to blogging--it requires little effort but over time provides useful pointers to where you were at the time."

* "Yeah, it's really helped with those 'now, what was that command line I used?' and 'how did I solve that problem last time?' type questions too. And not just for yourself. It also helps other people pick up 'incomplete' projects you might have lying around that you _cough_ haven't got around to documenting yet."

~~~
Noumenon72
I started keeping project logs on Confluence wiki recently and it is amazing
how much faster task switching goes without that "who wrote this?" effect and
all the "oh yeah, I went down this exact same blind alley of confusion last
time too."

------
TYPE_FASTER
Emacs in Org mode.

------
michaelmcmillan
echo ideas >> .gitignore

touch ideas

------
holydude
emacs org-mode and babel

------
holydude
emacs babel org-mode

