Core elements of programs - Documentation

Introduction

It can be hard to understand what a program is doing sometimes. And not just what it is doing, but why it is doing it. Imagine you’re trying to read someone else’s code, and you have no idea what it’s doing. That dosen’t sound very easy. Now imgainge you’re trying to read your own code… that was written at 3am 5 months ago. That also dosen’t sound very easy. Alternatively, try to imagine code that was written at 3am last night… and now it’s 4am, the day before compeition. That sounds like the exact opposite of easy.

Luckily, there is a convenient solution to this. It’s called documentation. Remember to always document your code. Pro-tip: always document your code.

Seriously: always document your code.

Syntax

Java let’s you document code in several different ways.

Single-line comment

You can write documentation for a single line with the // symbol. It can come at any point in the line, and after that point the compiler will just ignore what is said on that line. For example:

System.out.println((x+5/32((()((complicatedFunction()))aFancyThing()whichIs(hardTo(understand())); //An Explanation of what is happening
Multi-line comments

You can also write more complicated documentation that goes over multiple lines. Multi-line comments start with /* and end with */. Each line that is documented should start with * (eclipse/your IDE should help with that.) For example:

System.out.println((x+5/32((()((complicatedFunction()))aFancyThing()whichIs(hardTo(understand()));
/* A multi-line comment which explains:
 * 1. What is happening
 * 2. Why it is happening
 * 3. Decisions that were made
 * 4. etc.
 */
Javadoc

Java provides some super-helpful extra documentation tools to keep things easy to understand (and use). Javadoc helps you write useful documentation for functions, which will show a description, inputs, what it returns, and other tags (like author, errors it may throw) if desired. The javadoc will show in the “ctrl+space” autocomplete list, and if you hover your cursor over the function name (you may need to press f2 for it to show up.) Javadoc can also be used for classes.

To create some javadoc, on the line before the function decleration, type /** (two asteriks) and hit enter. Eclipse will auto complete some useful stuff (although you can always write it manually.)

Here’s an example:

/**
 * Tests if a given number is prime
 * @param numberToCheck The number to test primeness
 * @return True if prime, false if not
 * @author Tom Schwarz (SchwarzT18)
 */
public static boolean checkPrime(int numberToCheck) {
	for (int testingNumber = 2; testingNumber <= Math.sqrt(numberToCheck); testingNumber++) { //Only need to check to square root of number, as above are factors with a pair that has already been tested
		if (numberToCheck%testingNumber==0) {
			return false;
		}
	}
	return true;
}

You’ll notice that:

Writing effective documentation

You’ll notice that in the previous example, I kept documentation limited to only where it was needed. Documentation should be:

Note that variable names and function names should be descriptive.

Also Note that your code should (generally/nearlly always) be simple enough to not need excessive amounts of comments. If you go online, you will find some people who try to write code so neat and simple that it dosen’t ‘need’ comments. Other people claim the same thing, saying that it’s self-documenting, even when other people can’t understand it. All those people are wrong. Your code should be both simple and well-organized, and documented well. Generally I will split every couple (4-8) lines of code into blocks, which achieve/do something, and then put a short (~6 word) comment at the top saying what that block does.

Here are some example of bad comments:

int age = 32; //Sets age integer to 32.

/**
 * Modifies age variable
 * @param age the age
 */
public static int modifyAge(int age) {
	int age2 = age/2; //Halfs the age integer
	return age2; //returns the age integer
}

System.out.println(modifyAge(age)); //Outputs age

Not only is the documentation super-obvious and unhelpful, but it clutters the code and makes it hard to read. Function names and variable names need to be more descriptive, and the javadoc for the function is just stupid.

This is also bad:

String connectionStatus = getConnection("default");

/**
 * Get's the connection status for the passed name
 * @param name Should be the string name of the wanted connection
 * @return Doctrine_conection
 */
public static String getConnection(String connectionName) {
	return Connection.get(connectionName).getInstance().getDetail("Status").getValue();
}

Here the javadoc dosen’t actually tell you anything useful, rather just taking a lot of time to be confusing and over-detailed. Meanwhile the ridiculuos return Connection.get(connectionName).getStatus(); line, which needs an explanation as to why it’s code (and the code of Connection) is so horrifying.

Don’t let those examples of bad documentation deter you though. It is always important to document, even if it’s tempting not to.

Pro-tip: document.

Activities

This isn’t really something I can give an activity for… so there are none! If you want practice, feel free to go back and try documenting some of the code you wrote for previous activities. If you want some extra reading, here is a good article on documentation: https://medium.freecodecamp.com/code-comments-the-good-the-bad-and-the-ugly-be9cc65fbf83

Hope you enjoyed this module! You now know a lot about the basic of code. In the next module, Algorithims, we’ll start looking at how to write cool code to solve big problems.

Suprise! There are some activities, but they’re summary activities. Do document what you do though.

  1. Write a function which, when given two numbers, say a and b, returns a to the power of b. (No using Math.pow)
  2. Write a program which picks a random number and has the user guess what number it is, telling them if the number is higher or lower. (hint: see http://stackoverflow.com/questions/5887709/getting-random-numbers-in-java)