When working with a team of developers there are two skills I’d like to immediately transplant into everyone’s brains, Matrix Kung-Fu style. I enjoy working with people who can do these things well.
Write Code for People to Read
When writing code it’s easy to start focusing on solving the problem at hand and lose sight of the fact that your code will have to be maintained by other people. It’s easy to forget that people are your audience, not the computer. The computer doesn’t care about your comments, your formatting, your function names, or your abstractions. It just does what it has been told. You’re writing those things for people, and not just yourself.
Documenting ‘why’ is a very difficult skill. Why? Because when you are in the midst of writing code you already know why you are writing it. If you didn’t know why you were writing it, you wouldn’t be writing it. It’s so obvious to you in that moment why you are writing that code, you don’t feel you need to document it.
To effectively document ‘why’ you need to see the code as if you were seeing it for the first time. You need to get into the head of another person and have a good feel for when something is intuitive and when something needs more explanation.
If there is something I’d like to erase from their brains, Eternal Sunshine style, it would be the notion that code is self-documenting. Code can only explain what it is doing, not why.