Writing is one of the most powerful ways to communicate information. But, despite its power and ubiquity, writing is not well understood.
Code that communicates information quickly and accurately remains one of the challenges of our age. The title of this blog references a quote by Stephen King, who wrote: “If you don’t have time to read, you don’t have the time (or the tools) to write. Simple as that.”
In a similar vein, we believe that if you cannot write code that communicates information quickly and accurately, you will not be able to efficiently write code at all.
Code should be written to communicate information. There are important ways in which code can communicate information quickly and accurately. This blog will examine those ways.
1. The simplest way that code can communicate information is through its name. Names should be used consistently and appropriately. Ideally, a function or variable’s name should fully describe its function or contents, but if this is not possible due to the length of the name or the ambiguity of the function, then the name should at least be short and precise, and if possible, unique.
2. Another important way code can communicate information is through sensible structure: code should be arranged logically and intuitively, so that one does not have to search through it to find a particular piece of functionality; rather, when one desires to understand a certain part of the codebase as a whole, one should be able to navigate easily through it using conventional methods such as opening files or searching for keywords in relevant files. In addition, code should make use of comments whenever possible to concisely describe pieces of functionality that might otherwise confuse the reader; comments should not be used in place of sensible names (i.e., one should not get into the habit of simply commenting a function’s name) but rather they should explain in detail what something might do
Welcome to ht codeathon, a blog about the ways that code should be written.
In this post I will be talking about the coding style of a program I inherited from another programmer. The name of the program is cfbp and it is a C program intended to be used on Linux machines. It has been tested on Ubuntu 14.04 LTS, Red Hat 6.5, and Scientific Linux 7.0; it is not guaranteed to work on other versions of these OSes or on other OSes altogether. The program will print out the current date and time; read in a list of files specified by the user; calculate the size of each file; and print out the names of all files larger than 10MB in size, along with their sizes.
The main function begins by printing out the current date and time:
The next section is where the user specifies what files they want analyzed:
Then we have some code that checks whether or not any files were entered:
next we have some code that calculates the size of each file:
Finally we have some code that prints out a list of all files larger than 10MB in size, along with their sizes:
That is all for this post. Thank you for reading!
Writing code is about communicating information. Code should communicate information quickly and accurately to the people who are going to read it. It is important that those people be able to use the information quickly, and act on it.
The ways that code should communicate are:
Code should be easy to read. It should be as easy to read as normal English. If you have to squint at a line of code for more than a second, it is too hard to read.
Code should not waste time. If you have to squint at a line of code for more than a second, the reason should be because the line of code contains something very important, not because it contains unimportant details that distract from the main point.
Code should not be repetitive. Any two lines of similar-looking code are probably doing similar things. Similar things should be handled in a similar way, so that readers can understand them similarly.
The main purpose of code is to communicate information. The better the communication, the easier it will be for other people to work with your code. The easier it is for others to work with your code, the more time they will spend understanding and improving it, and the less time they will spend hunting down bugs and re-inventing solutions to problems that have already been solved.
There are three ways that code communicates information: at runtime, via documentation, and via source code itself.
Runtime: when the program is run, it produces some kind of output. Documentation: there are comments within the source code that explain what the program does. Source Code: without any help beyond variable names and method signatures, a person who understands programming can still understand much about what a program does.
It is possible for code to do a good job at one of these things but a bad job at another; this is not ideal. But if you have to choose which of these three aspects of communication to focus on improving, then Runtime is the most important, followed by Documentation and then Source Code.
The main purpose of code is to communicate information. This means that we should not be writing code for the computer, we should be writing it for other people.
The computer is a dumb machine that executes commands. The more complex the program, the harder it is for a human to understand what the computer is doing, so the less useful the code becomes.
If someone tries to figure out what the code does, they will be spending most of their time trying to understand something that doesn’t matter. This is why code should be simple and direct.
Most importantly, when you make changes to your code, you don’t want to have to spend all of your time trying to understand what you’ve changed.
If you have a hard time understanding what your code is doing, chances are good that someone else will have an even harder time understanding it. If others can’t read your code, then you don’t have a good communication tool; you have an obfuscated way of hiding information from them!
The concept of codeathon has become a household word in recent years. This word is usually used to refer to an event where developers come together to write code. Although this is a correct definition, it doesn’t give any insight into what a codeathon really is.
In its original meaning, “codeathon” was the name given to a type of hackathon that was held at the Y Combinator offices. The name was coined by Paul Graham in his seminal essay on how to write code. He described it as:
“The other half of the event was devoted to writing code. That’s how we came up with the name “codeathon.” It’s not just about learning, it’s about doing.”
This new type of event has inspired many people to start hosting similar events. In fact, there are now several different kinds of codeathons being held around the world, including:
Codeathons for specific languages such as JavaScript
Codeathons for specific frameworks such as Ruby on Rails
Codeathons for specific topics such as machine learning and artificial intelligence
Codeathons for specific technologies such as virtual reality and augmented reality
The purpose of these events is not only to learn how to write better code but also to share knowledge and build community