Short sentences

https://developers.google.com/tech-writing/one/short-sentences

1. Code and writing.

Minimize lines of code due as shorter code:

  • Easier to read
  • Easier to maintain
  • extra lines of code -> additional points of failure

Same rules for technical writing. Shorter documentation:

  • Faster to read
  • Easier to maintain
  • Extra lines -> Additional points of failure.

2. Focus each sentence on single idea

  • Statement of program: Single task
  • Sentence: Single idea.
  • Bad:

The late 1950s was a key era for programming languages because IBM introduced Fortran in 1957 and John McCarthy introduced Lisp the following year, which gave programmers both an iterative way of solving problems and a recursive way.

  • Good:

The late 1950s was a key era for programming languages. IBM introduced Fortran in 1957. John McCarthy invented Lisp the following year. Consequently, by the late 1950s, programmers could solve problems iteratively or recursively.

3. Convert some sentences to list:

  • Or in sentence - consider bulleted list.
  • Embedded list in sentence - List
  • Bad:

To alter the usual flow of a loop, you may use either a break statement (which hops you out of the current loop) or a continue statement (which skips past the remainder of the current iteration of the current loop).

  • Good:

To alter the usual flow of a loop, call one of the following statements:

  • break, which hops you out of the current loop.
  • continue, which skips past the remainder of the current iteration of the current loop

4. Eliminate or reduce extraneous words:

  • Textual junk, filters
  • Bad: An input value greater than 100 causes the triggering of logging.

  • Good: An input value greater than 100 triggers of logging.

  • Words to change

  • at this point in time -> now
  • determine the location of -> find
  • is able to -> can

5. Reduce subordinate clauses

  • Sentence: main clause and zero or more subordinate clauses
  • Subordinate - modify idea of main clause.
  • But less important.

Python is an interpreted programming language, which was invented in 1991.

  • main clause: Python is an interpreted programming language
  • subordinate clause: which was invented in 1991

Words to look:

  • which
  • that
  • because
  • whose
  • until
  • unless

  • since

  • Remember: Once sentence, one idea

  • Do subordinate extence one idea or branch off to second?
  • If divide, new sentence.

6. Distinguish that from which

  • Which and that used differently in countries.
  • In US.
  • which: nonessential subordinate clauses, pause while reading. Place comma
  • That: an essential subordinate clause. No pause. No comma.

Python is an interpreted language, which Guido van Rossum invented.

Fortran is perfect for mathematical calculations that don't involve linear algebra.