Issue 3 - Advice About Advice, Pitching Your Ideas, and Code Comments

Hello friends. The March edition comes to you much later than usual because on March 15th, I left my role at DigitalOcean, and on March 21st, I started a new role as Director of Education at Temporal.io, so things have been busy on the personal and professional front. But I still have a great issue for you that I hope you enjoy.

This month's issue takes a look at advice. First, we'll talk about all that social media content about how to get a new job, and why it might not be as valuable as it first appears. Then I'll share a tip about pitching your next article, book, or conference talk. Finally, I'll share my thoughts on one of the worst pieces of advice I hear developers give. Spoiler alert: it's about code comments.

Let's go!

Don't confuse "it worked for me" with "It will work for you" when it comes to the job hunt!

Every day you'll see someone on social media say, "I got hired at Google, and you can too. Just do what I did. Oh, and like and follow for more!"

Be very, very careful. The only thing this person can tell you is what worked for them. These people don't see all of the candidates. They don't have the experience of recruiters who successfully place hundreds of people each year and have worked at several different companies.

And they are not telling you how many rejections they got. And in some cases, they're not telling you what networking connections helped them. They're not acknowledging how lucky they were to apply when they did so they'd be at the top of the stack. And in some cases, they are not recognizing their privilege.

I've also applied for over 50 jobs in the last few years, and I've been turned down for roles way more often than I've gotten offers. I have gotten offers with my current approach, but the offer I accepted was one where my friend made an introduction for me.

There is a lot more luck involved in getting a job than people want to admit. The best thing you can do is engage in activities to increase your luck. Create meaningful two-way connections with friends in the industry and cultivate those relationships. And seek out and listen to the advice of people who do understand hiring in your industry. Talk with recruiters, hiring managers, and others who have the experience to teach you things. These things combined will do more for you in the long term than following a lot of the trendy advice people share on social media.

There is nothing wrong with people sharing their stories about what worked for them. But they often try to extrapolate what they did into universal advice, or worse, they turn it into a sales pitch for their services. When you come across someone offering advice, check their background and see if they have that experience to back up their advice.

Fine-tuning your topic idea

When you're writing content on your own platform, you don't need to convince anyone that your ideas are worth reading, watching, or hearing before you produce them. But if you're looking to write for someone else, or speak at a conference, you'll usually have some kind of process where you have to pitch your idea. And then, a committee of people will review your pitch and decide if it's worth moving forward with your idea.

Getting through this process is a lot like getting through a job interview. You need to have a clear understanding of what they're looking for and how you can provide value to their audience.

I've served on a proposal committee at a publisher, a couple of conferences, and I reviewed hundreds of proposals as the managing editor at DigitalOcean. The people who select your content are looking for the impact it will have on their audience.

And it starts with your topic.

If you're thinking about pitching an idea, you likely already have a topic in mind, but it might not be as fine-tuned as it could be. Before you try to convince others that it's a good fit for their audience, see if you can answer these questions:

• Why should the audience care? What's "in it" for them?

• What will they be able to do do that they couldn't do before?

• How does what you're going to cover relate to what they're already doing?

When you're excited about something, it's easy to focus on the how and the what. But when you're going to share things in writing or on a stage, you're doing it for the benefit of others. And your audience will have those questions. Adult learners have many things competing for their attention. One of the best things you can do for adult learners is to help them make good quick decisions about things and help them solve their challenging problems.

So sit with your topic and see how you can answer those questions. Then work those into your pitch. Make it clear what people will take away from your content. Make it clear what they'll be able to do or how they'll be able to think about things differently. Create that motivation that says, "You will have these new superpowers after reading this article or watching this talk."

You'll want to think about several other things when pitching, and my friend Mason Egger has a post on his blog that outlines how he approaches conference talk proposals, which offers another perspective you should read.

Ignore that advice about not needing comments!

If you've been around the programming world for a little while, you've seen or heard some variation of this piece of advice:

Comments are unnecessary if your code is clean

This is just terrible advice for a few reasons.

First, your definition of clean code may differ significantly from mine. Second, a comment block above a function helps give me context before I dive into that gnarly code. And finally, most programming languages have excellent tooling that turns your comments into documentation, and that tooling is only getting better.

The quality of a comment is what matters. If the comment is something like this:

// the SendEmailsToAllUsers function sends emails to all users

Then it's probably not that helpful.

However, a comment like the following will give you much more context:

​
/* the SendEmailsToAllUsers function expects an email template and the number of retry attempts.
This sends emails to all users by generating the message a template, creating EmailJobs in the 
messaging queue for each user using that template. The EmailWorker will pick these messages up 
and attempt to send them using SendGrid. If those fail, the EmailWorker will retry them using 
the number of retries specified when SendEmailsToAllUsers is invoked.
*/
​

And the software that generates documentation from these can identify other names and automatically hyperlink them for you so that EmailWorker becomes a clickable link, making it easier for you to browse those docs later.

Another use for code comments is to explain the intent of an algorithm. If you've inherited code from someone, you've probably wondered why they wrote something a certain way. And if you've been programming long enough, you probably attempted to rewrite something that looked like a bad solution, only to discover that the existing solution is the only way to do something. Or at least the least painful way, even if it's not the most efficient.

We make tradeoffs all the time in software. Deadlines and other constraints are constantly nipping at our heels. Corners will be cut. So comments give you a place to record assumptions, things you learned, and more. You can record that to save the next developer a bunch of work and provide them with that much-needed context they'd otherwise be missing.

I've been known to throw ASCII-art state diagrams in my code's comments. You can draw some great ones with ASCIIFlow.

Parting Thoughts

Here are some things to think about between now and the next time my newsletter finds your inbox:

0. What's something you're experienced with that you feel qualified to share with others? What's holding you back from doing that?

1. When you're looking at conference talk abstracts, what makes you most likely to attend a talk, other than the topic itself?

2. Do you know how to generate documentation from the comments in your codebase? What would that documentation look like if you generated it right now? Do you have some work to do?

Take some time to think about that first question. I bet every person reading this newsletter has expertise in one area that someone else will find valuable. Think about what that might be and how you can share it. You might just make a permanent impression on someone.

Thanks for reading this month's issue. If you found this helpful, let me know, and please share this newsletter with a friend.

I'd love to talk with you about this newsletter on Mastodon, Twitter, or LinkedIn. Let's connect!

Please support this newsletter and my work by encouraging others to subscribe or by buying a friend a copy of Exercises for Programmers, Small, Sharp Software Tools, or any of my other books.