Skip to content

Latest commit

 

History

History
149 lines (119 loc) · 9.38 KB

clean-code.md

File metadata and controls

149 lines (119 loc) · 9.38 KB
Raw

Writing Readable Code

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” — Martin Fowler

Developers spend SO MUCH more time reading code than writing it. This is true even with your own code. As a favor to yourself and whoever will need to use, maintain or develop your code, please learn to write readable code.

Documentation does not remove the need for readable code. Documentation is for users with no interest in reading source code; readable code is for developers who want to study, modify, fix, update, or in anyother way work with your codebase. (Including your futur self. Love yourself.)

There are many different opinions on what constitutes great JavaScript code. The most important thing is just that you're consistent. The war between coders that use tabs and coders that use spaces to indent their code is so engrained that it's essentially a joke by now, but it doesn't really matter as long as you're consistent.

Self-Documenting Code

Self-documenting code is code that reads almost like a very nerdy book.

You have already begun your journey towards self-documenting code and you didn't even know it. If you look to the process presented in tictactoes, the step from specs to empty code is giving you the start of a user-friendly project. The specs can become documentation for end-users, while the codebase is on it's way to being developmer-friendly:

  • The comments are pulled from the 'purpose' field of the spec - this gaurentees that you will have a 'why' comment for each component of the code.
  • You are building your code around pure functions.
  • The required functions, arguments, and return values are pre-declared with descriptive names.

Glorious.

Rules of Thumb

Structural:

  • Place all the 'workings' of your app in one place. This means function calls, important variable assignments (or reassignment), and any other lines crucial to understanding your code. With good naming, this can make your app read like a continuous story instead of a bunch of sentences split up through a phone book. (see example)
  • Use single-purpose, pure functions with simple, understandable behavior.
  • Have a helpful directory structure
  • Within a single file - organize variables, functions, objects, ... in a way that makes sense so you don't have to rescan the whole file all the time.

Naming:

  • All names of things describe what they do, even if it means having realllly long names.
  • Write helpful error messages
  • Decide on and stick to a naming convention. ie. camelCase or under_scores, var forty_two = 42, ...

Syntax:

  • Use prettier.js to make your coding style consistent. (white space, code blocks, functions, ... visually consistent)
  • Show intermediate values. ie. none of this: (array[3])()[title].name.splice(3)
  • Phrase things in the most clear way, not the most 'elegant' or short way. No one will care how brilliant you are when they're 15 minutes in and just starting to understand your code. (personal experience here)

Do Complete Refactors.

  • When your application or code changes, go through (at least most of) your codebase to reflect that change - modify variable and function names, reorganize what functions do what, even change your directory strucutre.

The better you are about starting with readable code, the easier it will be to keep your code readable.

Two Examples

1

Consider the following 2 snippets of JavaScript:

// difficult to read
const x = 
function(z) {
let w = 0;z.forEach(
function(q){
     w += q;
});return w;
};

x([2, 2, 2]);

// easy to read
const sumArray = function(array) {
  let sum = 0;
  array.forEach(function(number) {
    sum += number;
  });
  return sum;
};

sumArray([2, 2, 2]);

Believe it or not, both of those functions do the exact same thing (in the exact same way!), and both of them are perfectly valid code, but obviously the second one is much easier to follow. Imagine you're working on a project with someone else and they've written the first function... how long is it going to take you to figure out what's going on there so you can do your work? Imagine you're working on a project all by yourself and YOU wrote the first function a week or two ago... chances are good that you aren't going to remember exactly what you were up to there and it's still going to take you a good while to figure it all out again.

The second one, however, is much easier to follow. Even if you don't know exactly what everything in the code is doing, things are named clearly enough that you could guess, and the indentation is consistent enough that it's easy to parse the different parts of the function.

2

  •  // -----------  Define things in one place ------------ //
 var command_line_args = process.argv.slice(2);
 var first_arg = command_line_args[0];
 var second_arg = command_line_args[1];
 function check_input_type(input, expected_type) {
         // return true or false
     };
 function add_two_numbers(num_1, num_2) {
         // return the sum of num_1, num_2
     };
 function display_to_user(result) {
         // console log result
     };

 // ------------- Use the stuff you defined elsewhere --------------- //
 var first_arg_is_valid = check_input_type( first_arg );
 var second_arg_is_valid = check_input_type( second_arg );
 if (first_arg_is_valid && second_arg_is_valid) {
     var sum_of_args = add_two_numbers( first_arg, second_arg );
     display_to_user( sum_of_args );
 } else {
     display_to_user( " invalid argument types " );
 };

This is overkill for code that only adds two numbers, but it gets the point across. In more complicated or abstract programs the time spent writing clear code will more than pay off later.

Resources

Mandatory reads:

  1. avoid comments
  2. when you can't, make sure they help
  3. and certainly learn to know when they are apropriate
  4. code for the maintainer. They deserve your respect

Other resources:

Your Assignment

Read through these articles that discuss a few elements of writing good clean code.

  1. This article about self-documenting JavaScript. (It's not as crazy as it sounds)
  2. This list of clean-code tips.
  3. This article, and this one too about the role of comments in your code.

Bonus Section - LITERATE PROGRAMMING

If you take this concept to it's absurd conclusion you arrive at something called Literate Programming. In literate programming, the reader comes first and the computer second. A 'literate program' reads and looks like a story with code snippets where you would expect illustrations. We won't talk about this paradigm in class but it's worth a look if you're interested

Literate resources: