Sectionalised Code Comments

Preface

Since about 10 years ago when I started this style of commenting, I expected to see it naturally come about from the programmer community. It has not, and so I present it here.

Details

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#++ reject overlay {
# create overlay
@events.push
name:'click', target:@$el, selecter:'button.reject', fn:(e)=>
data = {}
data.ticket_id = $(e.currentTarget).dataId()
data.reject_type = $(e.currentTarget).attr('data-reject_type')
overlay_html = Template['campaign/reject_ticket.html'](data)
@overlay = Cmps.singleton('overlay',{html:overlay_html})
@overlay.$window.css('width','600px')
# overlay submit
@events.push
name:'click', target:$('body'), selecter:'.overlay_window .submit', fn:(e)=>
input = $(e.currentTarget).parents('.form:first').extractInput()
site.Api.method('ticket.reject', input).then (r)=>
if !r.success
return
collection.update({id:parseInt(input.id)}, r.data)
update_campaign_display()
@overlay.destroy()
#++ }

Rules

Absolute interactive indentation

1
2
#+ name {
#+ }

Ex:

1
2
3
4
5
6
7
8
#+ bob went home {
code...
code...
#+ bob drives into driveway {
code...
#+ }
code...
#+ }

relative not-interactive indentation

1
2
#++ name {
#++ }

Ex:

1
2
3
4
5
6
7
8
#++ bob went home {
code...
code...
#++ bob drives into driveway {
code...
#++ }
code...
#++ }

relative group-interactive indentation

1
2
#[group] name {
#[group] }

block section comment

1
2
3
4
#+++++++++++++++ Configuration +++++++++++++++
#+++++++++++++++ Configuration +++++++++++++++ {
#+++++++++++++++ }