Discussion on: How do you take notes while you code?

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

[Kaushal Joshi]

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

[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

jeremyf posted on Mar 21, 2022

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

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

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

View on GitHub

Note taking to understand a new-ish concept

The following DEV post is my note taking to learn.

Further Into Emacs with Pcase, Backquotes, and Commas

Jeremy Friesen ・ Mar 16 ・ 3 min read

#emacs #orgmode #todayilearned

Adding Documentation to Help Me Code

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

Adding inline documentation #16955

jeremyf posted on Mar 21, 2022

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:

Without Inline Docs

The "prior" state.

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

View on GitHub

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.

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

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.

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

[Harvey Thompson]

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

[Jeremy Friesen]

Yeah, me too.