How Comments Made Me A Better Programmer
I’ve found modifying the steps of a tutorial as I go to be helpful, though not very sticky. For example, if a program redirects a user to a thank you page after completing a sign up action, I could instead redirect them to their new account page. A flash message could appear, with the thank you message and a helpful next step.
I’m big into user experience, and this idea cuts out a step from the new user funnel. It’s more useful to send a new user to their account page after signing up, rather than a “Thanks for signing up!” page.
A page on how to get started using the app or service might be better than a simple account details redirect, but it’s a step up from a generic thank you page. A “Thanks for signing up!” page doesn’t add value to a user. It adds value to the people who own the program, because a static page is easy to track as the end step in a conversion.
Modifying a tutorial is a good way to think about extending functionality, but not a great way to understand how the code works, or how to describe solving a problem.
1) I don’t look at the answer until I’ve built a working solution.
2) When practical, I’ll change or extend the original exercise.
3) Hey, have fun!
I’m not a big fan of inline comments. Generally speaking, code should be readable enough for someone else to figure out what it does without relying on comments. Functionality and features to add later should live in a TODO.
But I’ve started using comments to describe how I think a program or script should function, before writing any code. It’s not quite pseudo-code, but more of a task list or an outline. I write out the steps of the program as I understand them, along with any obvious pitfalls.
The original exercise asks to calculate the area of a triangle with sides of length 5, 6, and 7. I’ve modified this for a couple of reasons. First, this isn’t much of a program. The most performant answer would be to simply do the math before hand, and print the result (14.6969). Not exactly in line with the spirit of the exercise, but the original is a pretty lousy program!
I’ve also mapped out a couple of obvious problems. I can’t expect users to always input valid numbers, so I’ll need to guard against values less than or equal to zero. Further, triangles have some fundamental rules. You can’t have a triangle with sides of length 2, 2, and 50, for example. So while I’m at it, I’ll protect against impossible values, as well as non-positive values.
At this stage, I’m not 100% on how I’ll guard against bad input. This program is starting to feel a lot like a form, so form field validation could be a good solution. It’s enough to throw a warning if the field contains a value I don’t expect. All that’s left is some math.
Now that I’ve got some ground rules in place for the problem I’m trying to solve, it’s just a matter of going through the steps, solving each part of the problem, and testing to make sure it works for a variety of inputs.
Here’s the working solution I came up with:
Using comments to map out the steps the program will need to take makes it easier to write the program later. For years, I thought programming meant you memorized every aspect of a language. It seemed impossibly hard!
But you don’t have to know everything. You just have to know how to describe the problem you’re trying to solve, break it up into manageable steps, and then complete those steps.
I don’t sit down to write a story without having some idea of what will happen in the story. It’s the same with programming. It’s why whiteboards exist.
Programming is problem solving. You have to solve the problem yourself first, and then tell the computer how to solve it.