Monty HarperJuly 29, 2024 at 8:29 AM
Do you take notes while you’re working on a personal coding project? I do, and I find it very useful for moving the project along and for consolidating my learning as I go.
iWeek App
I recently “finished” coding a project I call iWeek, meaning I completed a MVP version that works! iWeek is a to-do list app tailored for my own work situation. The app is designed to help schedule and track time spent on various projects throughout the week so nothing gets overlooked.
I spent about six months working on the app off and on, and I learned a ton in the process. My notes will help me leverage that experience into actual lessons learned, so my next app should go a lot quicker.
In all I wrote about 12,000 words worth of iWeek notes. That’s a third the length of a short novel! Over the past couple of days I’ve read through and tagged many interesting items. What this means for you is…
I identified about ten topics I could write about surrounding the making of iWeek, in addition to the two I’ve already posted (How to Get Things Exactly Backwards, and Clear Vision Not So Clear). So I’m launching a series of short articles about things I learned writing iWeek.
I’m starting off a bit meta in this article, with notes about taking notes…
My Platform
I keep notes on all my iOS projects in Scrivener, a desktop app designed to help authors keep their ideas and writing well organized. I’ve used Scrivener to write a few novels (I write fantasy and sci fi for middle-grade readers) and I love it so much, I now use it for everything.
My “iOS Development” Scrivener file includes a folder for 100Days of SwiftUI with a page on each lesson, notes on each project I did for my Udacity nanodegree, notes on my resume and job search efforts, notes and drafts for every article I’ve posted here on Dev, and notes on each of my original iOS app projects.
Of course, Scrivener isn’t the only piece of writing software good for this purpose, but I do recommend keeping your notes in one place, apart from your code. Some of my earlier code includes comments that really belong in a notes file. Code comments should be brief and relevant to a given line of code. The information I log in my notes file goes well beyond that.
Contents
The notes I kept for iWeek are all about communicating with my future self. Here are the sorts of things I wrote down:
Descriptions of being stuck. In my previous article I listed this as one way to get unstuck. Writing about your dilemma in detail can help you define the problem and identify possible solutions.
Good advice. When I sought outside help from a friend or peer group, I wrote down their suggestions.
Brainstorming. Often I listed several approaches that might solve a problem. As I tried each one I checked them off the list along with a note about how well it did or didn’t work.
Solutions to problems. This will help me navigate a similar situation more quickly in the future. Even if I never look it up again, the act of writing a solution down helps it stick in your memory.
Checklists or todo lists. This came in handy for things like coding all the buttons needed in a particular view.
Epiphanies. I found a few of these as I read back through, marked with asterisks and/or exclamation points! These lessons learned will form the basis for some of the future articles in this series.
References. Links to particular topics, examples, or important bits of code often saved me from having to search for the same thing again.
Habits
The notes you take are only useful if you use them. (Brilliant statement, don’t you think?) The following habits insured my notes were actually helping me with the project:
Date and time headings. In Scrivener, Shift-Option-Command-D will plop the current date and time into your document. I started each entry this way, adding it to the bottom of the document. These headings make it easy to see where each new entry starts, and they help a lot when scanning for recent information.
Review. Each time I sat down to work on the project, before diving into the code, I read the previous few entries in my notes to re-orient myself and set a goal for the current session.
Summarize. At the end of each work session I left myself notes on what I accomplished and what should come next. When I was stuck, I described the situation and wrote down any possible solutions that came to mind. This kept me from having to start the next session with no idea where to start.
Use specific keywords. Often I used Scrivener’s find function to review the history of a given class or function or UI element in my app. This works much better when the text references the actual names of the classes, functions, and elements used in the code.
Keep a sense of humor. Nobody else is reading my notes except for me. But I still gave them some personality and humor. That helps smooth over the rough patches. Here are some examples from my notes of language I would only use when writing for myself:
"It’s a thing of beauty. However, there are some bugs in there still, so I’m about to go bug hunting."
"Now it seems to work. There is a ghost in the machine."
"It’s a mess, man. It’s a real mess."
"Okay, making some kind of slow-ass progress… "
Conclusion
That’s about it. Do you keep project notes, too? How do they help you? Have I left anything out? Please post a comment!
