Dev Cycle
Tended:
Status: mature
The software development cycle from the perspective of a software engineer. I work on a team consisting of:
- ▪ 1 product manager
- ▪ 1 designer
- ▪ 1 person from marketing
- ▪ 5 engineers (senior through to grad)
The team is soley responsible for 1 product and uses an Agile approach including 1-week sprints and daily stand-ups.
1. What
Define what you are going to do. Gather as much information as possible. It will be the foundation of all work following it. The more time dedicated to this step, the stronger the understanding of the problem, the more likely a solution will present itself and the better everything proceeding it will go.
If I had an hour to solve a problem I'd spend 55 minutes thinking about the problem and five minutes thinking about solutions.”
If we can really understand the problem, the answer will come out of it, because the answer is not separate from the problem.”
Conversation
The best medium to collect information is a face-to-face conversation with the information provider(s). The product manager and designer in this context. It removes barriers that are present in other mediums, such as lack of body language in issue tickets.
Rewrite
Rewrite the information in your own words as a list, sketch pictures. Reading information gets you to 1 level of understanding. Parsing it, in your own language, gets you to the next level. Probe the information. Make gray areas clear.
Cost $
You might jump straight to React as the choice for creating the user interface. Composability that comes from React's component-based architecture is exceptional for scaling projects. You could also argue that in today's society, requirements change fast. Choosing a foundation that can scale is a good choice. But benefits come with costs. React increases bundle size and download time. When you consider a page should load in under 3 seconds, this could cost you users. The goal isn't to build the "perfect solution". It's to build something that has the best pros to cons ratio given the current information. Be aware of the pros and cons of your choices. Document them.
Take Hacker News as an example. It has grown its readership despite not adding new features over its lifespan. I would argue that React would have been a poor choice for this site. Due to the requirements of this site, the site’s complexity appears low. The cost of increased bundle size and library buy-in outweighs the scalability React provides.
2. How
This step defines how you are going to do it. Explore:
- ▪ The existing code base (if there is 1).
- ▪ APIs (Hoppscotch can help with this)
- ▪ Documentation
- ▪ Create functions, components, etc... in sandboxes (isolated coding environments). This is especially helpful if your using a library you're unfamiliar with. Tools that can help with this:
- ▫ RunJS
- ▫ Stackblitz
- ▫ Storybook
If the work involves a mockup, I'll annotate to help the thinking process. I use Excalidraw for this.
Based on the above and requirements, write out what you need to do in pseudocode. You want a clear idea of where you’re going before you start walking.
I do this in a .txt file (no styling, just tabs and letters).
3. Do
Using your pseudocode as a step by step guide, start coding.
Noise
Ekin Öcalan writes noise can enhance focus and creativity. But it can't be any kind of noise, it has to be noise that won’t attract your attention. Others having a conversation or music with lyrics attracts attention. Ambient noise, like water lapping the shore, won't. Noise cancelling headphones with Defonic can provide this.
Commits
Split pieces of work up into tasks.
Aim for each task taking no longer than an hour.
commit when I complete a task.
Think of commits as save points in a video game.
They reduce the chance of doing work more than once.
When making changes in unfamiliar areas in the codebase and things go wrong.
Tests start failing, the console floods with error messages and I'm in over my head.
I can clear all changes and start again from my last save point.
Save points give confidence to move fast and break things, knowing the work done up until this point is safe.
These commits are only useful during development. If pushed onto the main branch, they would flood the log with unneeded messages, making it harder to use. Before opening a PR, squash these commits to a single commit using:
> git rebase -i HEAD~3 // squash the last 3 commits_For the commit message, I use a convention.
Documentation
Documentation can come in many forms:
- ▪ The code itself by minimizing control flow, using explanatory variable names, and packaging it logically (through modules, files and functions).
- ▪ Comments.
- ▪ Unit tests.
- ▪ External documentation (such as a Confluence page).
It's best to select which approach to use on a problem-by-problem basis. As opposed to a strict policy such as we only write unit tests. Each form has strengths and weaknesses.
Code can describe how, but it cannot explain why.”
Communicating using multiple approaches can be more fruitful than attempting to be strict and only using 1 approach. For example, use code to describe the how and comments to explain the why.
Keep in Constant Communication
This is the longest step in the problem solving process. Effective teams have a strong shared understanding. Provide status updates of your work throughout this step to stakeholders. Tools such as morning huddles can help enforce this.
4. Review
Once you finish coding, walk away. After coding for an extended period of time, you can get tunnel vision. Going deep and solving something complicated while making simple mistakes in the surrounding area. Take a break. Go for a walk. Come back to your work with fresh eyes and check:
- ▪ Does it fulfill all requirements.
- ▪ Can the code be simplified.
- ▪ Can this be maintained.
- ▪ Is the code testable and have tests been written.
- ▪ Performant
- ▪ Documented
- ▪ Secure
- ▪ Scalable
5. PR (pull request)
Submit a PR. To help your team review your work:
- ▪ Size: keep your PR small. The smaller, the easier for reviewers to understand.
- ▪ Title: is a high level description of what's being solved.
- ▪ Description: should guide the reviewer through the code, highlighting related files and grouping them into concepts or problems that are being solved. Use text, mockups, screenshots (before and after), looms. Whatever is best to help communicate.
- ▪ Commit Messages: should talk about what changed and why. Not how (how is in the diff).
Pre-empt questions
As soon as you've opened a PR, you should pre-empt reviewer questions by looking for any potentially surprising changes and adding a line-specific comment explaining why you made the change.”
Mark isn't referring to comments explaining a line of code (the belong in the codebase), but comments that explain a change. Comments that only make sense in a PR context. You can also open a draft PR to enable commenting while indicating to others your work isn't ready for review.
When you think everything's understandable, Publish your PR and add reviewers. 1 thing I used to do was to start the next task while waiting for reviews. I think this is a mistake. While working on a problem, you build up context. When you start working on another problem, that context begins to decay. You want to maintain that context until the code has been merged. You want to be able to respond quickly and accurately to any comments or questions as well as confidently make any required changes.
6. Flexibility
In my experience, the above steps don’t occur in order. Rather, you will be jumping back and forth between them as you start building context in your mind. For example, while coding, you build more of an understanding of what the task requires. Time estimations made in the information step may need to be revisited and tasks removed. A better analogy would be to think of them as nodes in a graph rather than steps on a linear line.
Talking with a designer, they mentioned that this pattern is similiar in his work. The Double Diamond is a popular design process model. On paper, his team uses this model to solve problems and it pleases management when it comes to reporting. However, the Design Squiggle is a more accurate representation of the process.
