Answering why

In the past few years, I have had a pleasure working with some truly inspiring and bright people. Throughout this period, I have learnt a ton from them, and lately, I have noticed that few key points that were pointed out to me very early in my career make more sense now than ever before.

asking “what” is not enough!

Like many other software engineers, I like to describe what my piece of code does as it’s quick and easy, and it doesn’t require a lot of mental effort. However, answering what my code does isn’t enough. By failing to explain the reasoning behind the implementation, might potentially introduce confusion and decrease productivity for everyone involved later on. Besides this, by just answering what my code does, duplicates my effort of naming packages, functions, variables descriptively to provide implicit knowledge of what my code does.

learning from my own mistakes

In retrospective, I enjoy critiquing the code that I have written as it allows me to reflect and learn from my mistakes, and to use this as a metric to measure my growth as a software engineer.

// WithMessageType sets the message type
func (s *Sender) WithMessageType(t MessageType) *Sender {
	mt := string(t)
	s.MessageAttributes[MessageTypeSMSAttribute] = &sns.MessageAttributeValue{
		DataType:    aws.String("String"),
		StringValue: &mt,
	}
	return s
}

In the above function comment is very weak. I fail to state why the message type needs to be set. Is it an optional parameter? Does it override some default value? It was clear to me when I wrote the code! Now, a few months later, I might not have a clue. Furthermore, as the function name is self-explanatory, it renders my comment useless.

avoid questioning later

I try to imagine myself one year later, what questions I might be asking? Why message type needs to be set? Why Sender even cares about the message type? Furthermore, I try to think about what other software engineers might think when they would see my code for the first time, and I try to answer all their question beforehand. By spending some time questioning things now will definitely make life a lot easier in the future.