The Art of Readable Code – Extracts

Source: The Art of Readable Code–Extracts

Basic Rules:

• Code should be easy to understand.
• Code should be written to minimize the time it would take for someone else to understand it.

Surface-Level Improvements

• Picking good names,
• Writing good comments,
• Formatting your code neatly

About names

The best names are ones that can’t be misconstrued—the person reading your code will understand it the way you meant it, and no other way. Unfortunately, a lot of English words are ambiguous when it comes to programming, such as filter, length, and limit.
Before you decide on a name, play devil’s advocate and imagine how your name might be misunderstood. The best names are resistant to misinterpretation.

• Packing Information into Names
• Choosing specific words
• Avoiding generic names (or knowing when to use them)
• Using concrete names instead of abstract names
• Attaching extra information to a name, by using a suffix or prefix
• Deciding how long a name should be
• Using name formatting to pack extra information

Naming Booleans

When picking a name for a boolean variable or a function that returns a boolean, be sure it’s clear what true and false really mean.

In general, adding words like is, has, can, or should can make booleans more clear.

It’s best to avoid negated terms in a name.

Lines of code

Instead of minimizing the number of lines, a better metric is to minimize the time needed for someone to understand it.

Variables

1. The more variables there are, the harder it is to keep track of them all.
2. The bigger a variable’s scope, the longer you have to keep track of it.
3. The more often a variable changes, the harder it is to keep track of its current value.

Functions

1. Look at a given function or block of code, and ask yourself, “What is the high-level goal of this code?”
2. For each line of code, ask, “Is it working directly to that goal? Or is it solving an unrelated subproblem needed to meet it?”
3. If enough lines are solving an unrelated subproblem, extract that code into a separate function.

One task at a time

Here’s the process we use to make code do “one task at a time”:

1. List out all the “tasks” your code is doing. We use the word “task” very loosely—it could be as small as “make sure this object is valid” or as vague as “iterate through every node in the tree.”
2. Try to separate those tasks as much as you can into different functions or at least different sections of code.

Quotes

“Luck favors the prepared mind only” - Louis Pasteur

”Success and rest don’t sleep together. “- Russian proverb

”About motivate problematic people:  create a rich picture, reframe your goals, stage the encounter”

“Reasonable people adapt themselves to the world. Unreasonable people attempt to adapt the world to themselves. All progress, therefore, depends on unreasonable people.”
— George Bernard Shaw, an Irish playwright and a co-founder of the London School of Economics.

“Tact is the art of making a point without making an enemy.”
— Howard W. Newton, an American advertising executive and author.

“To avoid criticism do nothing, say nothing, be nothing.”
— Elbert Hubbard, an American writer, publisher, artist, and philosopher

“An expert is a person who has made all the mistakes that can be made in a very narrow field.”
— Niels Bohr

“Victorious warriors win first and then go to war, while defeated warriors go to war first and then seek to win.”
Sun Tzu

“Intellect distinguishes between the possible and the impossible; reason distinguishes between the sensible and the senseless. Even the possible can be senseless.”
Max Born

“When I’m working on a problem, I never think about beauty. I think only how to solve the problem. But when I have finished, if the solution is not beautiful, I know it is wrong.”
— Buckminster Fuller, an American engineer

"Good managers motivate with the power of their vision, the passion of their delivery, and the compelling logic of their reasoning"

“A man speaks with his heart, thinks with the history and lives to change it” – Nibor

Architecture

Architecture is about looking at a system from a point of view that makes it appear simple, sometimes artificially so. It provides a way of looking at the "conceptual essence" of something without getting bogged down in every detail.

An architectural viewpoint

It has to be simple to understand, to describe, to compare with other viewpoints, and, ultimately, to implement.
The viewpoint might seek a broad approach to a big, sweeping problem. Then again, it might be a thematic idea that can generate a family of similar solutions to a crowd of similar little problems—that is, a design pattern.

Adopting such a viewpoint inevitably limits one's implementation choices. That can be good. If all options are open, ten similar problems in your project might get solved using ten different techniques. That can require up to ten times more work than solving them all with a single technique, outweighing the usually meager benefits of handcrafting each solution. It can take up to ten times as much effort for a new developer to understand how the code works. And when it comes time to change the approach(es), it might take up to ten times as much effort to make that change (since you'd have ten different starting points). So, limiting variation saves time, makes things much easier to understand, and lets you discover and factor out common code much more easily.

When we simplify enough, and in the right way, we wind up with a viewpoint that contains a small number of concepts to think about, each of which has a clear set of responsibilities, relationships, and interactions with the others. It points the way forward on multiple fronts. A viewpoint like that is usually a sign of a successful architecture.

Made to Stick: Why Some Ideas Survive and Others Die–Extracts

Source: Made To Stick

Making your ideas sticky

What's my point? And why does it matter? If your audience remembers only one thing, what should it be?

Process for making your ideas stickier

1. Identify the central message you need to communicate—find the core;
2. Figure out what is counterintuitive about the message —i.e., What are the unexpected implications of your core message? Why isn't it already happening naturally?
3. Communicate your message in a way that breaks your audience's guessing machines along the critical, counterintuitive dimension. Then, once their guessing machines have failed, help them refine their machines.

Principles

1. Simplicity. The Golden Rule Is The Ultimate Model Of Simplicity: A One-sentence Statement So Profound That An Individual Could Spend A  Lifetime Learning To Follow It.
2. Unexpectedness
3. Concreteness
4. Credibility
5. Emotions
6. Stories

Steps

There are two steps in making your ideas sticky-

1. is to find the core, and
2. is to translate the core using the SUCCESs checklist.

The Zen aesthetic values include (but are not limited to):

• Simplicity (Kanso)
• Subtlety
• Elegance (Shibumi)
• Suggestive rather than the descriptive or obvious
• Naturalness (Shizen)(i.e., nothing artificial or forced),
• Empty space (or negative space)
• Stillness, Tranquility
• Eliminating the nonessential

Facts

• Simple messages are core and compact.
• People will attempt to change their behavior if
  they believe it will be worth it, and
  they can do what is required.
• Remember, stories need to deal with both
  “Will it be worth it?” and “Can I do it?” When it comes to changing behavior, nothing else matters