- Make systems as observable as possible. Stuff will break, the easier it is to identify the cause, the better. Logging things at different program flow points helps immensely.
- Question every decision in the codebase you are working on, but thoroughly weigh any refactoring attempts
- Don’t fall in love with own code
- Prefer readability over performance (in most cases)
- Don’t follow trends blindly. More than likely your boring stack is the best way to go
- Allow room to recover from a malformed system state
- Don’t abstract prematurely. If you struggle with designing your abstractions, you are probably good with concrete case(s) for now
1. Deeply understand the problem before you start writing code.
2. Provide in depth summary and explanation of the problem and solution in your PRs
Engineers can waste months or years of their collective time because they don't understand the problem they are trying to solve. They slap bandaids and fight wack-a-moles.
Both steps I listed above combat this issue.. the person(s) dedicated to solving the problem must understand the root issue with certainty. And when they explain their fix/solution it must be articulated well enough for other engineers or your future self to understand reliably.. else the mistakes of the past will be repeated.
Most engineers ask "why" to the surface level questions. E.g. "Why is the bug doing this instead of that?" A: "Oh, because this conditional does thing..simple, just fix this conditional. Solved!"
Then the issue pops up again... The engineer probably didn't ask why enough.
The should have investigated more... "Why did the original author choose this logic instead of the alternative? Was it purposeful, or was it a truly logical mistake?". If it was purposeful, why was this alternative not considered? What was Product's intentions here?" etc. etc.
Depending on context, that might be comments written on the ticket, a notes file (that I delete when I open a PR), or todo notes (with my initials) that I either resolve or defer to another ticket before opening a PR (and I have a `git todo` alias to find them all).
Partly this is just so I don’t have to rely so much on my memory. Partly this is communication to the rest of the team.
Sometimes I leave a comment on my ticket at the end of the day saying what I’d say about it in standup the next day. Which is good for me when I come back after the weekend, and good for the rest of the team if I spend a day or two off ill. It makes it easier for someone to pick up where I left off in my absence, if necessary.
2. Review my own PRs before I ask anyone else to.
If I can fix all the obvious nits before someone else looks at it, that frees them up to notice more fundamental issues that I’m blind to.
3. Commit early, commit often. Especially if I’m having a bad brain day.
- Write meaningful commit messages
- Make systems as observable as possible. Stuff will break, the easier it is to identify the cause, the better. Logging things at different program flow points helps immensely.
- Question every decision in the codebase you are working on, but thoroughly weigh any refactoring attempts
- Don’t fall in love with own code
- Prefer readability over performance (in most cases)
- Don’t follow trends blindly. More than likely your boring stack is the best way to go
- Allow room to recover from a malformed system state
- Don’t abstract prematurely. If you struggle with designing your abstractions, you are probably good with concrete case(s) for now
1. Deeply understand the problem before you start writing code.
2. Provide in depth summary and explanation of the problem and solution in your PRs
Engineers can waste months or years of their collective time because they don't understand the problem they are trying to solve. They slap bandaids and fight wack-a-moles.
Both steps I listed above combat this issue.. the person(s) dedicated to solving the problem must understand the root issue with certainty. And when they explain their fix/solution it must be articulated well enough for other engineers or your future self to understand reliably.. else the mistakes of the past will be repeated.
This is so interesting. What is your process of understanding the problem deeply? How do you keep track of your progress?
Honestly.. just keep asking "why?".
Most engineers ask "why" to the surface level questions. E.g. "Why is the bug doing this instead of that?" A: "Oh, because this conditional does thing..simple, just fix this conditional. Solved!"
Then the issue pops up again... The engineer probably didn't ask why enough.
The should have investigated more... "Why did the original author choose this logic instead of the alternative? Was it purposeful, or was it a truly logical mistake?". If it was purposeful, why was this alternative not considered? What was Product's intentions here?" etc. etc.
That’s one of the crappiest quotes I’ve ever heard no offence, it just sounds self congratulatory and forced as if they hoped for it to be quoted.
- Take notes of past decision (what context, deadline, available skills on the team, compromises that had to be made...).
- MR/MR contains a ref to the ticket, an explanation of the changes, proof of work or way to test the change.
- Know how to leverage your tools (git, editor)
- Be curious [other languages, tools (formal methods, fuzzing..), fields (web if you embedded, or the other way around), maths ... ]
Proof of work is so interesting! For backend changes, does that mean curl commands? some screenshots?
Could you give me an example format of your notes? I would love to see the detail one can get from them?
1. Keep notes.
Depending on context, that might be comments written on the ticket, a notes file (that I delete when I open a PR), or todo notes (with my initials) that I either resolve or defer to another ticket before opening a PR (and I have a `git todo` alias to find them all).
Partly this is just so I don’t have to rely so much on my memory. Partly this is communication to the rest of the team.
Sometimes I leave a comment on my ticket at the end of the day saying what I’d say about it in standup the next day. Which is good for me when I come back after the weekend, and good for the rest of the team if I spend a day or two off ill. It makes it easier for someone to pick up where I left off in my absence, if necessary.
2. Review my own PRs before I ask anyone else to.
If I can fix all the obvious nits before someone else looks at it, that frees them up to notice more fundamental issues that I’m blind to.
3. Commit early, commit often. Especially if I’m having a bad brain day.
I want to know more about note taking!
I'll give you my example, when I am driving to work I might realize something or during lunch. In that case, what do you do?
like all trades of men
the most important skill i have
is showing up every day
Don't forget the client. I have found it extremely useful to watch the client use our software, particularly when new features have been added.