04: How to Write Code

WARNING This exercise is in DRAFT status, so there may be errors. If you find any, please email me at help@learncodethehardway.com so I can fix them.

In this exercise I'm going to explain how to write code if you're a beginner. The problem you have is you don't speak code natively, so I have to show you how to translate from your language to code. This is something I don't need to do since I've been coding for decades, but I still do this if I'm stuck and can't think of what to write. Don't think of this as a worthless technique is all I'm saying.

In the first part of this course you'll mostly be typing in code I give you, but in the second part you'll start creating your own little projects and this information will be very important. You should also be trying to use this process on your own as often as you can.

1. Write a Paragraph

Your first step in writing a piece of code is to write what you want that code to do as a paragraph or two of English (or your language). Just write it however it is in your head and then try to refine it with as much detail as possible.

Let's take your code from Exercise 03 and recreate it from a description of that code. Here's what I would write:

You need a main.go file that can print the words "Hello World" to the screen. First, add the package statement at the top for the main package. Second, you need to import the "fmt" package so you can use it. Third, you have to create a main function that Go will consider the start of your program. Inside that main function you will place the code to tell fmt to print the line "Hello World".

2. Create Lines

Once you have your paragraph written you'll convert it into lines that represent the steps in the paragraph. It's even better if you can make these a sequence of steps to complete what you want to do. One way to make this easier is to imagine trying to tell someone how to do it over the phone.

Here's my conversion of the ex03/main.go paragraph:

1. You need a main.go file that can print the words "Hello World" to the screen.
2. Add the package statement at the top for the main package.
3. You need to import the "fmt" package so you can use it.
4. You have to create a main function that Go will consider the start of your program.
5. Inside that main function you will place the code to tell fmt to print the line "Hello World".

This is the sequence of steps that your code has to execute to accomplish the goal.

3. Make Comments

Next you'll take your lines of instructions and place them into your code as commnets. Go uses // at the start of any lines it will ignore, and programmers use this to add commentary (aka comments) to their code. This helps other programmers (and yourself 6 months later) to understand why the code is written this way. The code already says what it does, so the comments are better to explain why.

Go ahead and delete your ex03/main.go file or create a new ex04 project, then create this file:

View Source file ex04/main-a.go Only

// You need a `main.go` file that can print the words `"Hello World"` to the screen.
// Add the package statement at the top for the `main` package.
// You need to import the `"fmt"` package so you can use it.
// You have to create a `main` function that Go will consider the start of your program.
// Inside that `main` function you will place the code to tell `fmt` to print the line `"Hello World"`.

4. Code Under Comments

Once you have your comments for each step your next goal is to write code under the comments that makes them work. You should write some code under a comment, compile it, fix errors, run it, and then repeat for each comment until it's working. This also gives you a chance to look up each thing you want to do for that comment.

Once you have these comments in place your job is to make each one work with the right line of code. This is most likely going to be the difficult part for you, but that's also why programming is challenging. Here's what I would do:

View Source file ex04/main-b.go Only

// Add the package statement at the top for the `main` package.
package main

// You need to import the `"fmt"` package so you can use it.
import "fmt"

// You have to create a `main` function that Go will consider the start of your program.
func main() {

    // Inside that `main` function you will place the code to tell `fmt` to print the line `"Hello World"`. 
    fmt.Println("Hello World")
}

Remember that you don't type all of this in at once and try to run it. You'll get too many errors. You should type 1 or 2 lines at a time, try to compile, and fix any errors you can. Sometimes Go will complain about you not using a variable or module so just ignore those while you work.

5. Delete Comments

After you have your code working go back and delete these comments so you only have code to view. With this fresh view do you see anything you need to change? When you work like this you will typically not have a good first version. It'll probably work, but it won't be that great, and that's fine. Programming is an educational process and you can just do it again based on what you learned.

View Source file ex04/main-c.go Only

package main

import "fmt"

func main() {
    fmt.Println("Hello World")
}

6. Refine or Recreate

Finally, take what you have and either refine it or recreat it again based on what you learned. There's times when I'll rewrite a first version of an idea 2 or 3 times to get it right. Each rewrite makes it better, or helps me see if my approach doesn't work so I can try a new one.

This example code is so simple that it doesn't need more refinement, but on larger code you would then step back and ask yourself if there's anything that go wrong? If there is then fix it, or take what you've learned and start over. Starting over is a great way to confirm to yourself that it was not luck.

Next Steps

The first module features very simple code but I'll frequently ask you to practice this process on recreations from memory. When we reach Exercise 06 you'll copy the code, then I'll have you delete it and recreate it this way. Doing this will vastly improve your ability to understand and remember code, which is a vital skill in programming. It's also an interesting challenge.