Having Readable Code

The importance of having your code understandable


When making open-source (or any software) readability is key. What do we mean by readability? Well readability is just making sure that your code is grammatically sensible. You can do this in multiple ways. One of the best ways is to leave comments. Let's take an example snippit Keter program that might not make sense on first glance.


f main() { arg = argv[0]; case arg { "-o": setOutput(argv[1]); "-r": remove(argv[1]); } }

While technically functional, it can be a pain in the butt to understand. The first, and MOST IMPORTANT way of making this readable is by using MULTIPLE LINES and indentation.


f main() {
arg = argv[0];
case arg {
"-o":
setOutput(argv[1]);
"-r":
remove(argv[1]);
}
}

While using multiple lines is beneficial, having comments adds a lot. Sure, while someone who has experience with the language, or programming in general, would know what is going on, a new programmer, or a beginner might not. Adding comments can also say what the file as a whole is supposed to do. Here is an example of good commenting.


// example.ktr
// Showing how the keter programming language works
// by Kai Lyons <[email protected]>

// This function automatically runs when the program is asked. No need to call it.
f main() {
// argv is an array of CLI arguments.
// Say someone runs a compiled "example.ktr" binary with the command saying "one two three" after the command.
// What this does is the program understands these, and we can use them to understand what the user wants the program to do.
arg = argv[0];
case arg {
// The "-o" argument asks for an output name. EX: "command -o file.new"
"-o":
setOutput(argv[1]);
"-r":
// The "-o" argument asks for a file to delete. EX: "command -r file.new"
remove(argv[1]);
// If neither "-o" or "-r" are provided, the program exits with an error.
default:
e: "Requires -o or -r!" }
}

Downsides? Well unless you care (or need to care) how big your code is, say your repo is limited on storage, or your computer is limited on storage, then not really. Comments are always omitted from the compiled binaries for Keter-made applications, and ignored in interpreters and transpilers for Keter. This means there is no real issues for binaries. If you really need to avoid comments at ALL COSTS, you can simply have a version without comments. Whether this be a branch for your repo, or just a separate file without comments. There is the possibility of over-commenting a program, however usually that isn't a problem. To comment properly, say what you are doing in simple terms, and only explain the overview. If you REALLY NEED to add a lot of extra information, like what functions uses that line of code, or what files call that those lines of code, best to do that in some form of developer documentation.