An introduction to coding for beginners

In this article I’m going to show you an example of a computer program, including looking at the Python code behind the app. I’ve made my example beginner-friendly where possible.

I particularly want to get across a few points:

• You don’t need to write much code to achieve a lot of functionality
• More important is understanding what you’re trying to do and which pre-existing tools you can use
• Python is user-friendly to both beginners and experts alike
• The above three bullet points were not true 20 years ago and the role of a software engineer is changing as a result

Most of this boils down to Python is awesome and you should give it a go, so without further ado here’s the example app, written in Python.

espanol-encuentro

The app is called espanol-encuentro, which means “Spanish encounter”. It’s a dictionary from Spanish to English which I wrote to help myself learn Spanish.

The code for the app is stored on an online platform called github — see luke-chapman/espanol-encuentro.

The code and what it means

This Python program is contained within a single file called example.py. You can find it on github, or see the copy below:

# Section 1 - imports
# Let's re-use some pre-existing tools to make life easier for ourselves
#
# For example, we're going to use the 'json' Python library to interact with data in the json format
# json is a beautiful, simple and ubiquitous data format - if you're interested, see https://www.json.org/json-en.html

import json
import sys
from argparse import ArgumentParser
from pathlib import Path


# Section 2 - argument parsing
# Our program will be invoked by command lines such as:
#
# python example.py add comida --part-of-speech noun_f --definition food
#
# We need to tell the program what the arguments in these command lines mean
# 'ArgumentParser' also emits useful help messages or error messages to help the user
#
def run():
    parser = ArgumentParser()
    subparsers = parser.add_subparsers(dest="mode")

    add_parser = subparsers.add_parser("add")
    add_parser.add_argument("word", help="The Spanish word to lookup")
    add_parser.add_argument("--part-of-speech", "-p", required=True)
    add_parser.add_argument("--definition", "-d", required=True)
    add_parser.add_argument("--examples", "-e", nargs="*")
    add_parser.add_argument("--related-words", "-r", nargs="*")
    add_parser.add_argument("--words-dir", type=Path, help="Directory containing json files for each word")

    delete_parser = subparsers.add_parser("delete")
    delete_parser.add_argument("word", help="The Spanish word to delete")
    delete_parser.add_argument("--words-dir", type=Path, help="Directory containing json files for each word")

    lookup_parser = subparsers.add_parser("lookup")
    lookup_parser.add_argument("word", help="The Spanish word to lookup")
    lookup_parser.add_argument("--words-dir", type=Path, help="Directory containing json files for each word")

    list_parser = subparsers.add_parser("search")
    list_parser.add_argument("--starts-with", "-d")
    list_parser.add_argument("--words-dir", type=Path, help="Directory containing json files for each word")

    args = parser.parse_args(sys.argv[1:] or ["--help"])

    # Section 3 - a little bit of a setup
    #
    # espanol-encuentro stores the words in a folder on your computer
    # Let's decide what that folder is and create it if it doesn't exist
    #
    words_dir = args.words_dir or Path.home() / ".espanol-encuentro" / "words"
    words_dir.mkdir(parents=True, exist_ok=True)

    # Section 4: if-else statements
    #
    # What operation are we doing? Either 'add', 'lookup', 'search' or 'delete'
    #
    if args.mode == "add":
        # Section 4a - 'add' operation
        #
        # We create a 'dictionary' object called 'entry' and write it to a json file
        #
        entry = {
            "word": args.word,
            "part_of_speech": args.part_of_speech,
            "definition": args.definition,
        }
        if args.examples:
            entry["examples"] = args.examples
        if args.related_words:
            entry["related_words"] = args.related_words

        word_json = words_dir / f"{args.word}.json"
        with word_json.open("w", encoding="utf-16") as w:
            json.dump(entry, w, indent=2, ensure_ascii=False)
        print(f"Wrote entry for '{args.word}' to {word_json}")

    elif args.mode == "lookup":
        # Section 4b - 'lookup' operation
        #
        # Look for the json file and print its contents if it exists
        #
        word_json = words_dir / f"{args.word}.json"
        if word_json.is_file():
            print(word_json.read_text(encoding="utf-16"))
        else:
            print(f"No entry found for '{args.word}'")

    elif args.mode == "search":
        # Section 4c - 'search' operation
        #
        # Start by listing all the files in the words directory
        # If we specified --starts-with, filter this list accordingly
        #
        words = sorted(d.name[:-5] for d in words_dir.iterdir() if d.suffix == ".json")
        if args.starts_with:
            words = [w for w in words if w.startswith(args.starts_with)]
        print(f"Found {len(words)} words matching criteria")
        print("")
        for word in words:
            print(word)
        print("")

    elif args.mode == "delete":
        # Section 4d - 'delete' operation
        #
        # If there's a file for the word in question, delete it
        #
        word_json = words_dir / f"{args.word}.json"
        if word_json.is_file():
            word_json.unlink()
            print(f"Deleted entry for '{args.word}'")
        else:
            print(f"No entry found for '{args.word}'")

    else:
        # Section 5 - error handling
        #
        # What if the mode isn't add, lookup, search or delete?
        # Let's report this error back to the user (comedy link: https://www.youtube.com/watch?v=x0YGZPycMEU)
        #
        raise ValueError(f"Unexpected mode '{args.mode}'")


# Section 6 - a tiny bit of magic to start and stop the program
#
if __name__ == "__main__":
    sys.exit(run())

There’s a lot going on in the above code. Don’t worry if it doesn’t all make sense to you — learning a programming language takes time, just as it’s taking me time to learn Spanish.

What I’m hoping comes across is the following:

• In less than 100 lines of code we’ve got a working computer program which can add, lookup, search and delete entries in a Spanish-English dictionary. You don’t need much code to do a lot!
• We didn’t write it all ourselves. Those 4 imports at the top — argparse, json, pathlib and sys — allow us to use code someone else wrote in our program, through a well-defined API (application programming interface)
• To complement the above beginner-friendly program, I’ve also written a more advanced and robust version of the app. In luke-chapman/espanol-encuentro you’ll find testing (pytest), linting (ruff, mypy, black), continuous integration (GitHubActions), packaging (hatch) and documentation (markdown) next to example.py. It’s beyond the scope of this article to explain what all of the above tools mean; suffice to say that Python is a language with depth and breadth and programmers of all experience levels are always adding new tools to their toolbox

Let’s give it a go…

If you want to get your hands dirty you should be able to use espanol-encuentro on your computer. There are installation instructions here: espanol-encuentro/README.md. Alternatively you can just read below to see how the program works.

espanol-encuentro is invoked from the command line. On Windows you can use Command Prompt to input your command lines; on Mac it’s called Terminal.

I was a bit nervous and confused around command lines when I started programming, but don’t be afraid! Command lines are just a way of giving an instruction to a computer — similar to clicking on a website link, or launching Microsoft Word. Command lines are popular amongst programmers because they provide low-level control over what the computer is doing.

Once you’ve followed the installation instructions and started up your Command Prompt or Terminal, try running the following commands:

python example.py

python example.py add comida --part-of-speech noun_f --definition food
python example.py add bebida --part-of-speech noun_f --definition drink --examples "Quiero una bebida (I want a drink)" --related-words comida

python example.py lookup comida
python example.py lookup bebida

python example.py search
python example.py search --starts-with b

python example.py delete comida
python example.py delete bebida

The above commands highlight the different things you can do with espanol-encuentro:

• Display a help message
• Add the words comida and bebida to the dictionary
• Lookup the words we just added
• Search the dictionary, once for all words, once for all words beginning with b
• Delete comida and bebida from the dictionary

Here’s a screenshot of the output from my terminal from running these commands on 2024–08–13:

In summary

In this article we saw an end-to-end example of a computer program, complete with the source code, to give you an insight into modern software development. For sure, writing the code is important and remains a primary skill of a software engineer. However, understanding what you’re trying to do and what pre-existing tools you can make use of are equally important nowadays.

If you want to get into programming there are numerous resources available online:

• If you’re got a mathematical background you might enjoy Project Euler
• There are lots of resources for learning Python. This official one is pretty comprehensive: The Python Tutorial — Python documentation
• Please please please, we need more women in software! I know of the PyLadies community and the well-priced SheCodes courses to help women’s presence in the field grow

Finally, becoming expert in anything — software, a foreign language, you name it — will take time and require lots of hard work. The quality of technology is so high nowadays it’s easy to think it’s all magic and just works. It’s not magic, and it doesn’t just work! Every small component has been thought through by everyday people taking small steps. You can be one of them — good luck!