DEV Community

Adam Davis
Adam Davis

Posted on

How do you take notes while you code?

Do you like to take notes when you're writing code?

Do you organize them in some way, or do you only keep notes about your current tasks?

What pieces of information do you think are helpful to keep track of?

Discussion (61)

Collapse
panditapan profile image
Pandita

I normally take notes on Obsidian: my to-dos, daily reflection, meetings notes, definitions and so on.

If I'm extremely and highly stressed out I start to brain-dump everything on paper. For me, it feels like I'm moving things from my brain to somewhere else and I can see it much clearly than with my computer.

I feel that for my brain, the computer is just an extension of itself, but paper? nope, it's a place to vomit feelings/thoughts/ideas/etc 😂 I think this is due to my teen years where I would draw a lot. Every idea, thought, feeling was set on paper and promptly forgotten hahaha

Collapse
brewinstallbuzzwords profile image
Adam Davis Author

I don't know the last time I've resorted to using paper, but sometimes if I need to sketch some diagrams out with my Wacom tablet

Do you like Obsidian? How does it compare to Notion?

Collapse
panditapan profile image
Pandita

aah I wouldn't be a good person to ask regarding Notion vs Obsidian because I was never properly able to use Notion! it would distract me more than I actually using it hahaha I would make pretty dashboards one day and the other? eeeeh I wouldn't do anything with it.

Obsidian sorta allows me to create and use all my creativity without distracting me. It really does help me focus on writing rather than "designing my dashboard to be aesthetic" 😂

Thread Thread
brewinstallbuzzwords profile image
Adam Davis Author

Ah, gotcha. I guess I haven't delved too deep into what Notion can do, since I didn't realize it was possible to spend that much time making things look better haha

I mostly use it for writing my blog posts and keeping a schedule of when I'm going to publish things

Thread Thread
panditapan profile image
Pandita

I suggest a small search in pinterest for notion 😂

I use obsidian mostly for work, to handle my work planning. My personal obsidian is more for jotting down things I don't want to forget or saving information or thoughts about subjects I'm interested in, not so much for planning (I do a little bit for non code projects). I use paper planners for weekly home planning since I really like my stickers and washi tape :3

Thread Thread
abelardusbm profile image
Abelardus

Would you happen to know the difference between Obsidian and Evernote?

Im just starting to take notes but insured about what tool is best.

Thanks!

Thread Thread
panditapan profile image
Pandita

Hi, sorry for the late reply!

I actually decided on Obsidian as a replacement for Evernote :surprised: I used Evernote a lot to take notes, I really liked the editor and the notebook organization they have going on but the discoverability of whatever I wrote down wasn't as good, or at least I wasn't really good at it. I also didn't like how it was a web app that would limit the access to my notes unless I paid (or logged out constantly and I'm more of a remember me type of gal). I don't have that trouble with Obsidian because my notes belong to me and are in my computer (I should link it to a git repo though, but for now it's fine), I pay for the sync between my phone and computer and that's it. I don't depend on a 3rd party in this case!

Also, Obsidian has a really nice, supportive and helpful community! I really suggest looking for beginner resources because when you open Obsidian for the first time you'll feel like looking at a blank paper! so many possibilities xD

But, the only way to find out if a platform is for you is to test it out! that's how I know if something works or not for me c:

Collapse
ericzedd profile image
ericz • Edited on

Not OP, but have used both.

Notion is your 'use-however-you-want' software, and you can practically customize it in anyway that you see fit. You can soure your stuff from different databases, linked into one dashboard, table, kanban, or calendar view

Obsidian on the other hand is a very streamlined note taking app. But despite of, it does a really good job of linking references to what you're currently working on without getting distracted.

EDIT: Ohh OP beat me to the "getting distracted" part 😅

Collapse
tmchuynh profile image
Tina Huynh

I have been looking into Obsidian. It looks like a wonderful application to start using.

Collapse
panditapan profile image
Pandita

it is!! it can also send you through a personal knowledge management rabbit hole which is an experience I personally really enjoyed 😂

Collapse
jeremyf profile image
Jeremy Friesen

When writing code, my notes are my code, tests, comments, commit messages, and issue tracker. If that's inadequate for "thinking", I'll step away and either grab pen and paper or start an org-roam node to begin thinking by writing.

My default fallback for any note taking is my personal knowledge management tool (org-roam).

Collapse
clumsycoder profile image
Kaushal Joshi

Can you please share a small piece of your notes as reference? This sounds helpful...

Collapse
jeremyf profile image
Jeremy Friesen

Absolutely.

Communicating via PR with Benchmarks and intentions

The following PR is an example of some notes I took regarding performance as well as minor refactoring.

Removing instance variable and before action #16954

What type of PR is this? (check all applicable)

  • [x] Refactor

Description

There is no reason to create an instance variable as we don't pass this to the view. Further, by adding this as a before_action there's a disconnect in logic.

This commit attempts to address those issues.

What follows is a three-fold change:

  1. Removing the before action (let's just call the method)
  2. Reworking the method to reduce, just a bit, the method cost
  3. Removing an unused instance variable

Here are the benchmarks. Note the "follows_limit" as written below is the "Proposed" route.

require 'benchmark'

def follows_limit_original(params:, default: 80, max: 1000)
  per_page = (params[:per_page] || default).to_i
  @follows_limit = [per_page, max].min
end

def follows_limit(params:, default: 80, max: 1000)
  return default unless params.key?(:per_page)
  per_page = params[:per_page].to_i
  return max

  per_page
end

def follows_limit_alt(params:, default: 80, max: 1000)
  per_page = params.fetch(:per_page, default).to_i
  return max if per_page > max
  per_page
end

TIMES = 10_000
Benchmark.bmbm do |b|
  b.report("Original no params") { 1000.times { follows_limit_original(params: {}) } }
  b.report("Original less than max") { 1000.times { follows_limit_original(params: {per_page: 90 }) } }
  b.report("Original greater than max") { 1000.times { follows_limit_original(params: {per_page: 9000 }) } }
  b.report("Proposed no params") { 1000.times { follows_limit(params: {}) } }
  b.report("Proposed less than max") { 1000.times { follows_limit(params: {per_page: 90 }) } }
  b.report("Proposed greater than max") { 1000.times { follows_limit(params: {per_page: 9000 }) } }
  b.report("Alt no params") { 1000.times { follows_limit_alt(params: {}) } }
  b.report("Alt less than max") { 1000.times { follows_limit_alt(params: {per_page: 90 }) } }
  b.report("Alt greater than max") { 1000.times { follows_limit_alt(params: {per_page: 9000 }) } }
end
Enter fullscreen mode Exit fullscreen mode
$ ruby /Users/jfriesen/git/forem/bench.rb
Rehearsal -------------------------------------------------------------
Original no params          0.000403   0.000002   0.000405 (  0.000405)
Original less than max      0.000109   0.000005   0.000114 (  0.000114)
Original greater than max   0.000161   0.000006   0.000167 (  0.000166)
Proposed no params          0.000076   0.000001   0.000077 (  0.000076)
Proposed less than max      0.000114   0.000009   0.000123 (  0.000126)
Proposed greater than max   0.000112   0.000011   0.000123 (  0.000123)
Alt no params               0.000104   0.000007   0.000111 (  0.000114)
Alt less than max           0.000113   0.000009   0.000122 (  0.000122)
Alt greater than max        0.000111   0.000001   0.000112 (  0.000115)
---------------------------------------------------- total: 0.001354sec

                                user     system      total        real
Original no params          0.000108   0.000000   0.000108 (  0.000110)
Original less than max      0.000109   0.000001   0.000110 (  0.000111)
Original greater than max   0.000109   0.000000   0.000109 (  0.000109)
Proposed no params          0.000071   0.000000   0.000071 (  0.000071)
Proposed less than max      0.000103   0.000001   0.000104 (  0.000103)
Proposed greater than max   0.000102   0.000000   0.000102 (  0.000103)
Alt no params               0.000093   0.000000   0.000093 (  0.000093)
Alt less than max           0.000103   0.000000   0.000103 (  0.000104)
Alt greater than max        0.000102   0.000000   0.000102 (  0.000103)
Enter fullscreen mode Exit fullscreen mode

Related Tickets & Documents

  • Related to forem/forem#16913, forem/forem#16942

QA Instructions, Screenshots, Recordings

This is a noop change.

UI accessibility concerns?

None.

Added/updated tests?

  • [x] No, and this is why:

[Forem core team only] How will this change be communicated?

  • [x] I will share this change internally with the appropriate teams

Note taking to understand a new-ish concept

The following DEV post is my note taking to learn.

Adding Documentation to Help Me Code

This PR is solely about improving my editor experience by adding documentation.

Adding inline documentation #16955

What type of PR is this? (check all applicable)

  • [x] Documentation Update

Description

While exploring the DashboardsController, I came across method calls to not_found. Idiomatically, I assumed that these methods were returning a value. However, in looking at the code, it raises an exception.

Note: I excpect methods that raise exceptions, especially as the only thing they do, to end in a !.

By adding the documentation my "IntelliSense" provides insight into the expected behavior of this function (e.g. "Raises an exception"). Without the documentation, I don't see any useful information.

With Inline Docs

The "proposed" state:

eglot-with-inline-docs

Without Inline Docs

The "prior" state.

eglot-without-inline-docs

Related Tickets & Documents

  • Related Issue #forem/forem#16913 (but only in the "I'm in the neighborhood looking at things kind of way").

QA Instructions, Screenshots, Recordings

None.

UI accessibility concerns?

None.

Added/updated tests?

  • [x] No, and this is why: It's a documentation only PR.

[Forem core team only] How will this change be communicated?

  • [x] I will share this change internally with the appropriate teams

Personal Note-Taking in my Dailings

Below is a screenshot of my high-level notes from 2022-03-24. I use these notes to help me remember what I worked on the day before.

A Screenshot of an Emacs buffer describing a few tasks, along with links

The following screenshot shows a calendar overview, I can use that to select the specific date.

A Screenshot of a 3 month calendar, some of the dates are highlighted indicating I have notes for that day

And the final screenshot shows two buffers: "Amy" on the left and backlinks to "Amy" on the right. The right are the headlines of the files that reference Amy. This builds up an ability to navigate a graph of information.

A screenshot showing the times I've referenced Amy in my notes

And as I write all of this, I think I have a blog post to consider. Which builds on this DEV post

Thread Thread
610yesnolovely profile image
Harvey Thompson

Before starting with org-mode, I wasn't sure if it was worth learning. Oh my, how wrong I was.

Thread Thread
jeremyf profile image
Jeremy Friesen

Yeah, me too.

Collapse
brewinstallbuzzwords profile image
Adam Davis Author

I like to keep a small text document of TODO items for my current ticket. If something is particularly complex then I’ll keep my notes saved for future reference, but there’s typically enough details in the ticket or the code / comments that I don’t need my notes after the fact.

Curious to see what other people take notes on and how it helps their coding process.

Collapse
bradtaniguchi profile image
Brad

I basically do this, but update/reply/edit the original ticket so if I were to get shifted to another task, someone else can leverage any notes/information I took.

Or if in the future I need to go back over the same ticket everything is in the same place, for me or whoever.

Collapse
brewinstallbuzzwords profile image
Adam Davis Author

That's a good point. Need to make sure enough information is there for someone who may work on it later

Collapse
sso profile image
Sall • Edited on

I used many tools, techniques until I tried github.com/xwmx/nb and learned how to automate and integrate. It became my all-in-one tool which do anything, anytime, and anywhere also has scheduled workflows and is integrated with multiple services like GitHub, Jira, etc.

Collapse
brewinstallbuzzwords profile image
Adam Davis Author

That's pretty cool. I hadn't heard of that tool before

Collapse
sso profile image
Sall • Edited on

Important to identify your needs and plan far ahead before choosing the services (as there is so many). The tool is not the most important part, but makes life a lot easier when the tool is right and well known. I recently started the whole organization for Z shell tools and their manager (Z shell is a powerful scripting language as-well). It's in early stage but I am pretty sure it can replace all your current tools and most of OS services. Welcome to use it or participate to make it better :) (Need support small and complex tasks).

z.digitalclouds.dev
github.com/z-shell

Collapse
dgloriaweb profile image
dgloriaweb • Edited on

I use Jira, however I don't think it couldn't be better. All my notes go into the backlog, as a subtask or as a comment. Every time I feel that I'm done with what I was working on, I return to the task, and read it again, making sure that my change was actually what the task was. So my notes are there, eg. if a flash message is red not green, I won't stop and fix it, I add it to the task as a subtask and continue with the current work. I use notebook (pen and paper) if I have to work out logic. If it's math, I use notebook, if it's flow, I use whiteboard and take a picture.

Collapse
brewinstallbuzzwords profile image
Adam Davis Author

That's a good point about adding subtasks. I definitely need to get better about that, since it's so easy to start fixing a bunch of small things that I come across

Collapse
jonrandy profile image
Jon Randy • Edited on

Handwritten notes on my reMarkable tablet - one of the best things I ever bought

Collapse
brewinstallbuzzwords profile image
Adam Davis Author

What else do you use it for? I've looked into getting one before, but I don't know if I'd use it enough to justify the price

Collapse
jonrandy profile image
Jon Randy

It handles PDFs way better than a Kindle, so I use it for reading stuff too. I used to go through an awful lot of paper taking notes, but this is much easier to manage

Thread Thread
brewinstallbuzzwords profile image
Adam Davis Author

I occasionally read PDFs on my Kobo (an e-reader that's pretty similar to a Kindle) but haven't done it in a while since it doesn't handle them super well. I can see how I'd probably take more notes while reading if I could write directly on the document

Thread Thread
jonrandy profile image
Jon Randy

You can indeed write directly on the document

Collapse
cerchie profile image
Lucia Cerchie

When there's a long command idiosyncratic to a codebase I actually throw it in my Slack messages to myself -- avoids multiplication of apps.
I should figure out how to alias these though-- any good resources?

Collapse
brewinstallbuzzwords profile image
Adam Davis Author

I think I'd probably use Slack in that way if my company didn't have messages set to auto-delete after a certain amount of time

If you have idiosyncratic commands that are really common in a codebase, it might be helpful to create a development.md file for quick reference

Collapse
cerchie profile image
Lucia Cerchie

That's a great idea!

Collapse
fjones profile image
FJones

I tend to have a scripts folder in my home dir, usually set up as executables with references to the working dir if needed. Shell aliases if they're more common.

Collapse
fjones profile image
FJones • Edited on

Transient notes go into Slack, open strands in code go into TODO-tagged comments (thanks JetBrains for letting me find them easily!), and more persistent notes go into a root-level TODO/README, our wiki, or as a printout on the whiteboard.

Relevant personal notes just get dumped onto the desktop, with cleanup every year or so during business downtime.

For development sketches and so on, I just go pen&paper. Usually have a small A6 booklet with me for that purpose, and scribble down ideas and plans while sitting on the deck.

Collapse
skydevht profile image
Holy-Elie Scaïde

Right now, I'm adding Craft to my workflow. I can keep a lot of information in my head, but that tires me. So I jot them down. That have also reduce my development time. It's mostly things that I would talk to someone else if I was working with a collaborator. I've also use goodnotes as a whiteboard when I need to break down a tough problem. If I'm doing research, I dump everything in apple notes to organize and distill later.

Collapse
610yesnolovely profile image
Harvey Thompson

I use Emacs' org-mode - which is essentially a text file (similar to markdown) but with more dynamic abilities: tables, todo lists, tree like organization, code blocks (that can be executed and pipelined).

Each project has such a file, and it's versioned with Git or Perforce. This is the most part: versioning and switching between projects is fairly easy.

For large projects, even if the company uses something like Jira, I'll still keep notes and Jira links in this file, so I can list which bugs or tasks I'm working on - often I'll get interrupted or have to fix something quickly, so it really helps with context switching.

Collapse
tmchuynh profile image
Tina Huynh

I love using Pocket to keep tabs of everything I think I will go back to, resources that could be useful overtime, etc. Other than that, I use my bullet journal to write down pieces of information I may learn each day and index them as needed. If needed and specific to the project I am working on, I'll add comments to the document for me to return to the next day or following week.

Collapse
brewinstallbuzzwords profile image
Adam Davis Author

I've been using Pocket intermittently for years. I always seem to forget it exists a couple months after I start using it, then try it again a year later.

Do you have any spreads in your bujo that you find particularly helpful for this sort of thing? Or does most of it end up in your daily logs?

Collapse
waigani profile image
Jesse Meek

I use CodeLingo Notebooks for code notes.

It's like Notion for devs. It's a web doc with markdown formatting, but you can insert "blocks" that integrate with editors and VCS hosts (e.g. github): here's a video demo:

I mainly use code snippets that you can click on to locate the code in your editor again. So you can literally navigate the codebase with your notes.

For example, if I'm touching several bits of code across the repo, I go back to the note to remind myself what the next step was, click on the snippet and it loads the exact bit of code up for me in my editor.

It's got a bunch of other features on top, chatting with your team on a snippet, applying a patch etc.

Full disclosure, CodeLingo Notebooks is my own project so I'm obviously biased but I can honestly say I can't imagine coding without it now. Super keen to hear people's thoughts.

Happy Coding 😊

Collapse
alexisfinn profile image
AlexisFinn

Don't usually take notes just to myself.
1- If it concerns the functionality it should be add to the ticket
2- If it's a todo-list of things I need to do on my current ticket add it to the commit message
3- If it's something technical concerning the code it should be documented in the source-code
4- If it concerns architecture, how to install/run, add it to the repository README

Collapse
spaquet profile image
Stephane Paquet

It depends on the nature of the note.
When the note is intended to be shared I will just write it in the code using an highlighter tool to make sure it's visible. This way the notes can be quickly shared with my peers.
When it's a note that require discussion: Notion
When it's a note for me, I will drop it in my Notion note section.

Collapse
diballesteros profile image
Diego (Relatable Code)

I use notion, I write some cheatsheet type things down and maybe some key interactions. I try to keep it at a bare minimum.

Mostly try to focus on actually trying to implement what I'm studying so it sticks more. At least thats whats worked for me.

Collapse
just5moreminutes profile image
Just5MoreMinutes

I always take notes or write down my TODO-list when coding. I like to use Trello (trello.com) because of it's simplicity and nice features. If I'm working on a smaller project, I like to make little notes on post-its and stick them on the edges of my screen. That often results in a quite weird looking screen setup, but at least I got an overview of everything :)

Collapse
utkarsh736 profile image
Utkarsh736 • Edited on

I don't take notes anymore as it wasn't helping me but rather taking up a lot of my time.
I just try to practice the concept in code and look to alter it to grasp a better understanding.
If there is a point that I always seem to forget or find myself googling it repeatedly then I note that point down just anywhere(don't usually read it again) but just writing it makes me remember it.

Also, if it is a tutorial type project then I add simple comments for me to understand later.

Collapse
hollyw00d profile image
Matt Jennings

As someone who has rewritten way too many comments in the past, I:

  1. Add the bulk of my comments in the projects README.md file which should be at the root of a git repo.

  2. Add two or one lines of comments in code files, excluding the README.md file. A great example I've used for brief comments are the official React repo:
    github.com/facebook/react

Here's an example file with brief comments:
github.com/facebook/react/blob/mai...

Collapse
googlicius profile image
Hai Dang

I created a file NOTE.md in my root project directory, and listed it in .gitignore file.

Collapse
brewinstallbuzzwords profile image
Adam Davis Author

I like that idea. Lets you have personal notes in the same directory as the project but without sharing it with everyone

Seems like this would be a good use case for a global gitignore so you wouldn't need to ignore it on every project

Collapse
zakirsajib profile image
Zakir Sajib

I use notion app

Collapse
chadalen profile image
Chad Adams

Joplin 🙂

Collapse
ben profile image
Ben Halpern

I either take notes in a physical notebook, or in my local kanban board (I use kanbanier for Mac, a simple app) where I track status.

Collapse
brewinstallbuzzwords profile image
Adam Davis Author

Do you feel like using a physical notebook slows you down? It seems like that would make things more difficult if you need to reference certain functions or file names

I could see it being helpful for limiting distractions though

Collapse
sherrydays profile image
Sherry Day
Collapse
brewinstallbuzzwords profile image
Adam Davis Author

Thanks, I'll check it out

Collapse
agustind profile image
Agustin

Notion

Collapse
mikeyolang profile image
Michael Otieno Olang

I always use Markdown to take notes and a piece of paper to sketch the project

Collapse
frisodenijs profile image
Friso Denijs

It depends on what the notes are for:

  • If they relate directly to the code and are useful to the team, then I add it as comments
  • If they are to remember to do something that's out of scope at the moment, then I add them as item(s) to the backlog
  • If they are lessons learned, then I add them to my lessons learned repo on GitHub
  • If they are to visualize an idea for me, then I sketch it on paper
Collapse
muhyilmaz profile image
MUHAMMED YILMAZ

Trello.

Collapse
cgifl300 profile image
cGIfl300

draw.io a mindmap is vital

Collapse
chettyusa profile image
RAJU CHETTY

Analyze the past explore the future

Collapse
lehacode profile image
LEHAtupointow

I've got many TODO comments and IDEs highlightt them for me. Eric6 has this nice littlle TODO list for all loaded files.