Skip to content

Instantly share code, notes, and snippets.

@hzhou
Created August 21, 2015 16:13
Show Gist options
  • Save hzhou/2dd36570d10646898510 to your computer and use it in GitHub Desktop.
Save hzhou/2dd36570d10646898510 to your computer and use it in GitHub Desktop.
Literate Programing vs. Commenting

Note that the code:

$call go_to_school

subcode: go_to_school
    $call get_bag
    $call put_on_shoes
    $call get_out_of_door
    $call wark_toward, school

subcode: get_bag
    ...

is different from:

# go to school
$call get_bag
$call put_on_shoes
$call get_out_of_door
$call wark_toward, school

On the surface the comment summarizes the intention of the code and serves as high level view, but 1. it does not deliminate well -- it is not clear on the scope of that comment; 2. it didn't isolate -- the lower level detail is right on the surface. We cannot prevent ourselves to delay reading it if it is right on the surface.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment