SC code review

• R4: code review
  • code review
  • DRY: don’t repeat yourself
  • Comments where needed
  • Fail fast
  • avoid magic numbers
  • one purpose for each variable
  • use good names
  • Use whitespace to help the reader
  • don’t use global variables
  • Methods should return results, not print them
  • avoid special-case code

R4: code review¶

• code review: read and discuss code written by others
• General principles of good coding: things you can look for in every code review(与编程语言和目的无关的)

code review¶

• Purpose
  • Improve the code
  • improve the programmer
    • 新语言特性，项目设计的改变，its coding standards, new techniques…
• Style standards: 除了特定语言的规范，比如google C++/java/… style guide，还有许多部分值得审视
  • spec, ADT with representation invariants, concurrency and thread safety
  • be a team player: 在写pj时考虑别人已经写了的部分的风格

DRY: don’t repeat yourself¶

• avoid duplication

Comments where needed¶

> where to comment¶

• Specifications document assumptions
• Specify the provenance of code that was copied from elsewhere
  • Reason
    • Copyright
    • Answers change fast

//function: read a web page into a str
//see web:http://...
........

• Obscure code
  • 一串莫名其妙的公式

> where not comment¶

• direct transliterations of code into English
  • assume readers at least knows java

Fail fast¶

code should reveal its bugs earlier as possible

• static checking
• Dynamic checking
• …

avoid magic numbers¶

Magic numbers：一串莫名其妙的数字

• do not hardcode; reason
  • a number is less readable than a name
  • constants may need to change in the future
  • Constants may be dependent on other constants
• use named constants
• When there are many magic numbers, treat them as data and consider to store in data structures.
  • Easy to understand: uncover the hidden relationship. 存储在某数据结构中并不能保证这一点。
  • Ex: 0, used as an integer value,作为计数的最小值或identity value in addition; symbolically, magic number.

one purpose for each variable¶

Don’t reuse variables/parameters. (我之前还不太习惯用太多变量名)

//final: variables can't be reassigned.

use good names¶

• what to do

  • follow the lexical naming conventions of the language
    • Python/java: Classes, setVariableName(java), set_variable_name(python)
    • Global constants(public static final): use capitalization in java, ALL_CAPS_WITH_UNDERSCORES
    • Local variablesL use camelCaseNames like secondsPerDay
  • method name: verb phrases
  • Variable, class names: noun phrases

• what not to do

  • No abbr/single-character variable names except conventional one

Use whitespace to help the reader¶

• don’t use tab for indentation; use space instead
  • why: tab represents numbers of spaces in different languages
  • 只要将tab设置成相应的空格就行了。

don’t use global variables¶

• Global variable: accessible and changeable from anywhere in the program
  • final: unchanged

public static ... 

• Kinds of variables
  • local variable: inside a method
    • Disappear when the method returns
  • instance variable: inside an instance of an object (belong to certain class instance)
    • created when calling new object; disappears when object is no longer accessible
    • each object instance has its own instance variables
    • 别名：field, property, member variable, attribute
  • Static variable: associated with a class(belong to class itself)

Methods should return results, not print them¶

• except debugging output: aim to debugging the design

System.out //sends result to the console

avoid special-case code¶

• Resits to handle special cases separately
  • Special cases add complexity and hide possible bugs
  • Special cases is not exactly related to overall performance.
• think for the general case.
  • Broader, general-case code pay off.