[dylan604]

in procedurally written scripts, i write "what" comments as an outline or roadmap. i also use # vs // differently where the // style designates these what so i can find next to jump to next section. if i ever get away from being a solo dev and work as part of a team, there'll be a lot of unlearning personal habits

[andruby]

What you describe as sections seem like natural breaking points for function. Split of those section in their own named function. The names help to document, make it easier to test and the calling of the functions will give a high-level overview of the processes

Ie:

  def drive
    turn_ignition()
    shift_gear()
    press_accelerator()
  end

  def turn_ignition
    … code
  end

  def shift_gear
    …

[chrisjharris]

I think this is exactly right. Function names actually fulfil the role of documentation really well. I personally tend to make them long and quite verbose, like

`def start_the_car_and_accelerate`