Ask HN: Coding notes – how do you do them? | Hacker News Reader

Ask HN: Coding notes – how do you do them?

68 pointsosullivj81 comments

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++'s Find in Files is invaluable for navigating them. There was a thread last year on paper notes [1], but I'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?

[1] https://news.ycombinator.com/item?id=11890742 [2] https://en.wikipedia.org/wiki/GrandView_(software)

View on HN

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

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

#!/bin/bash

# https://stackoverflow.com/questions/7131670/make-bash-alias-...

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

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.

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

How did you keep notes on the implementation process?

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

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.

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

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.

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.

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.

I second OneNote, been using it for years.

Microsoft has a mobile app "Office Lens". Useful to take pictures of the papers. It auto-corrects the positioning of the frame.

asciiflow.com is great for rendering simple schematics and diagrams as plain text.

Not related to coding notes, but I type my university lecture notes in LaTeX, and over the years I've picked up enough TikZ to write down graphs and diagrams in near-realtime.

I thought I was pretty decent with TikZ, then I read this. That's extremely impressive - nice job!!

Atom has an extension that allows you to mouseover a base64 string and see the image output

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

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.

I use Quiver for my coding notes http://happenapps.com/#quiver

Quiver is a life saver for me. Markdown, i can use my vim keybindings, the data format is just json, easily taggable and searchable. I save my snippets, observations, commit history, everything in quiver now. It is synced via dropbox as well

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.

I'm another very happy Quiver user.

I make mind maps of what ever topic I am learning / researching. (https://github.com/nikitavoloboev/my-notes-mindmaps#github-i...)

I then add it to to the main research (https://my.mindnode.com/83qmKgoATj8TyKzprzsPfoirxa2g9WmFGx3x...) 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...).

Great insight, thanks for posting.

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

Now that's something I'd love to see! Care to share?

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 :)

Clearly, you're familiar with this:

https://en.wikipedia.org/wiki/Fundamental_theorem_of_softwar...

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?

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.

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]

https://github.com/divbit/grimoire

Example output pdf for sharing:

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.

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

All roads lead here, IMO!

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

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/ [1]: http://happenapps.com/

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

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

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.

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.

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`

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

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.

> 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/

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

Thank you

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

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.

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.

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#

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

http://tiddlywiki.com/

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.

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

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)

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.

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

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.

I love 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.

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

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

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

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

Org mode and never look back.

http://orgmode.org/

I use my own app MarkNote (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!

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

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.

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

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.

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.

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.

I use my CatWiki wiki software https://github.com/cabalamat/catwiki

@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)

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.

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.

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

zim desktop wiki since 2008. Works well with Dropbox.

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/ 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 (I started my journey by using a single-file wiki tool: 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...

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-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=2914071

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

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

Emacs in Org mode.

echo ideas >> .gitignore

touch ideas

emacs org-mode and babel

emacs babel org-mode

Reply on news.ycombinator.com