It is currently Fri Oct 20, 2017 8:22 pm

All times are UTC - 7 hours





Post new topic Reply to topic  [ 24 posts ]  Go to page 1, 2  Next
Author Message
PostPosted: Fri Jan 20, 2017 3:47 am 
Offline
Formerly WheelInventor

Joined: Thu Apr 14, 2016 2:55 am
Posts: 907
Location: Gothenburg, Sweden
Scissoring this from my previous thread on vector terminology:

tokumaru wrote:
WheelInventor wrote:
Has this been mentioned in previous threads? I haven't informed myself on this.

I normally mention it every time someone posts code with that comment. The code itself isn't wrong, it's just the comment that's misleading. $2003 doesn't "set the low byte of the address", seeing as the sprite DMA always starts copying from $XX00, $XX being the value you write to $4014. What $2003 does is select the DESTINATION address, inside the OAM, where the data will be written to.


It made me reflect on tutorial commenting praxis in general. Normally when commenting for myself, i try to tell my future self what a line or block is for, rather than what it literally does. Is this however good praxis when writing a tutorial? I often have a feeling tutorial comments can be a little off, but it's hard to pinpoint when you're still learning the ropes.

Oh, and any other thoughts about tutorials and in-example code commenting could go in this thread, too.

_________________
http://www.frankengraphics.com - personal NES blog


Top
 Profile  
 
PostPosted: Fri Jan 20, 2017 4:16 am 
Offline

Joined: Thu Aug 20, 2015 3:09 am
Posts: 284
My rule of thumb is that comments should always explain why. The what should be obvious from the code itself. Readable code is much more important than comments, but any time you're doing something for a reason that's not immediately obvious, you should add a comment to document it.

For tutorial code, that means the comments should explain why you need to/should do certain things. For example, why you need to do your scrolling writes to $2005 at the end of your NMI handler, or why you should wait for the NMI handler to set a flag rather than polling $2002. If you're familiar with the NES they're a matter of course, but if you're not you may think they're just the way the tutorial writer happened to do it. Knowing the reason for everything makes the reader much more likely to remember it.


Top
 Profile  
 
PostPosted: Fri Jan 20, 2017 5:13 am 
Offline
User avatar

Joined: Sat Feb 12, 2005 9:43 pm
Posts: 10065
Location: Rio de Janeiro - Brazil
WheelInventor wrote:
Normally when commenting for myself, i try to tell my future self what a line or block is for, rather than what it literally does.

That's what I do too. I only comment something line by line if it's something *really* hard to follow.

My comments try to explain what's going on in plain english, like I was talking to a person who's not a programmer. I do my best to avoid terms like "array", "flag", "register", or anything that's too technical.


Top
 Profile  
 
PostPosted: Fri Jan 20, 2017 8:21 am 
Online

Joined: Sun Sep 19, 2004 11:12 pm
Posts: 19113
Location: NE Indiana, USA (NTSC)
At the end of the init code in my NES project template, I write this:
Code:
  ; There are two ways to wait for vertical blanking: spinning on
  ; bit 7 of PPUSTATUS (as seen above) and waiting for the NMI
  ; handler to run.  Before the PPU has stabilized, you want to use
  ; the PPUSTATUS method because NMI might not be reliable.  But
  ; afterward, you want to use the NMI method because if you read
  ; PPUSTATUS at the exact moment that the bit turns on, it'll flip
  ; from off to on to off faster than the CPU can see.

Is that the kind of "why" you expect?


Top
 Profile  
 
PostPosted: Fri Jan 20, 2017 9:08 am 
Offline
Formerly WheelInventor

Joined: Thu Apr 14, 2016 2:55 am
Posts: 907
Location: Gothenburg, Sweden
Here's two cases in the library i'm building to teach myself, dividing even simple code up in short macro blocks named after their circumstantial function (which means sometimes similar or identical macros have different names with different descriptions - reading a register may be to get a flag, or to reset something).

Everything is neatly organized after 'cases' or 'functions', and it complies with my intention to "tell my future self what it is for", but it doesn't use Rahsennors' "why"?. Reading it some time after, it looks like mysticism, which is bad. In the macros, i use direct addresses with their corresponding constant commented. I think the idea is to see them/write them side by side and learn them through repetition.

Code:
;============================
;IN CASE OF TROUBLE ROUTINES
;============================
;
;
;---------------------------------------------------
.macro reset_vram
;---------------------------------------------------
;Used to avoid graphical glitches whenever your code
;may cause updates to take longer than
;the vblank period. If the addr stored in $2006
;(PPU Address) at that point is = $0000,
;the glitch won't appear.
;---------------------------------------------------
      LDA #$00
      STA $2006 ;PPUADDR
      STA $2006
.endmacro


Compared to tepples' why, mine doesn't tell much. I didn't know the benefit of the other method, so it couldn't really be any other way at this point:

Code:
;=================
;SPINLOCKS
;=================
;
;
;---------------------------------------------------
.macro wait_vblank
;---------------------------------------------------
;Use this in your init as a method to wait for
;the PPU to stabilize after powerup. It will break
;out of the spinlock when a NMI frame is
;done. It should be used twice during init.
;---------------------------------------------------
   @spinlock:
      LDA $2002 ;PPUSTATUS
      BPL @spinlock
.endmacro
;---------------------------------------------------

_________________
http://www.frankengraphics.com - personal NES blog


Last edited by FrankenGraphics on Fri Jan 20, 2017 9:14 am, edited 1 time in total.

Top
 Profile  
 
PostPosted: Fri Jan 20, 2017 9:13 am 
Online

Joined: Sun Sep 19, 2004 11:12 pm
Posts: 19113
Location: NE Indiana, USA (NTSC)
The long comment was typical of tutorial code. Production code might have a "doc comment", inspired by Javadoc comments, at the top of each subroutine and shorter comments inside. From my basic PPU routines:

Code:
;;
; Clears a nametable to a given tile number and attribute value.
; (Turn off rendering in PPUMASK and set the VRAM address increment
; to 1 in PPUCTRL first.)
; @param A tile number
; @param X base address of nametable ($20, $24, $28, or $2C)
; @param Y attribute value ($00, $55, $AA, or $FF)
.proc ppu_clear_nt

  ; Set base PPU address to XX00
  stx PPUADDR
  ldx #$00
  stx PPUADDR

  ; Clear the 960 spaces of the main part of the nametable,
  ; using a 4 times unrolled loop
  ldx #960/4
loop1:
  .repeat 4
    sta PPUDATA
  .endrepeat
  dex
  bne loop1

  ; Clear the 64 entries of the attribute table
  ldx #64
loop2:
  sty PPUDATA
  dex
  bne loop2
  rts
.endproc


Top
 Profile  
 
PostPosted: Sat Jan 21, 2017 5:54 am 
Offline

Joined: Tue May 28, 2013 5:49 am
Posts: 804
Location: Sweden
As my beginning projects acts like my notebook of how programming the system works, they are always full of comments of details of how to do things. My earlierst programs looked something like this:
Code:
  lda #$05  ;load 5 into the accumulator
  clc       ;clear carry
  adc #$03  ;add 3 + carry to the content of the accumulator

Plus it had large "doc comments" that explains hardware features like where every palette entry goes into VRAM and so on. Kind of like Tepple's examples but much more. This helped me remember what every instruction does and how the hardware in the NES works.

After I got more used to 6502 and the NES hardware my comments became much more scarce and I only explain what the result of every few lines do (sometimes even if it's a bit obvious). If the code is not very obvious I might comment almost every line to explain why it does what it does. I'm quite good at explaining things, if I may say so myself, so I never found it hard to explain what the code does and does so gladly. My NES hardware notes have moved to a separate reference document that I have open beside my project when I'm working. It summarizes every hardware register of the NES using my own words, so I can easilly look them up whenever I need to. This make my projects much less cluttered with comments, but I still like comments to explain most things, just in much shorter notes and with the assumption that the reader knows how the basics of how the hardware works.

Subroutines and macros still have doc comments though which explains in detail every input argument and output it uses, as well as any other requirements it has and sometimes example code of how I intend it to be called.


But the question is how tutorials should comment. I think doc comments and similar larger explanations are good in tutorials because it makes the source code almost work out as a tutorial itself. The Nerdy Nights sound tutorial is a good example of this. Anything that isn't explained in the lesson itself, is usually explained in the lesson's source code that you can download.

The Nerdy Nights comments about OAM-DMA using $2003 and $4014 is not about commenting praxis though. It's simply a misunderstanding that, whoever wrote that comment, made and as such is wrongly teaching this faulty fact to newbie NES developers (I was fooled by it myself). It should really be corrected.


Top
 Profile  
 
PostPosted: Sat Jan 21, 2017 6:39 am 
Offline
User avatar

Joined: Mon Jan 03, 2005 10:36 am
Posts: 2962
Location: Tampere, Finland
Out of curiosity: How many people in the English-speaking countries use the word "praxis" instead of "practice"? It's the first time I ever saw it, was surprised it actually is a word in English.

(N.B. "Praxis" means exactly "practice" in Swedish, so it's not that surprising to see two Swedes using it. :))

_________________
Download STREEMERZ for NES from fauxgame.com! — Some other stuff I've done: kkfos.aspekt.fi


Top
 Profile  
 
PostPosted: Sat Jan 21, 2017 6:54 am 
Offline
Formerly WheelInventor

Joined: Thu Apr 14, 2016 2:55 am
Posts: 907
Location: Gothenburg, Sweden
Hah! I'm not in a position to answer that, but i always took it for granted because of the close ties between latin and academic literature :lol:

_________________
http://www.frankengraphics.com - personal NES blog


Top
 Profile  
 
PostPosted: Sat Jan 21, 2017 10:21 am 
Offline
User avatar

Joined: Fri May 08, 2015 7:17 pm
Posts: 1780
Location: DIGDUG
In English, praxis is very rarely used, and would be considered highly academic... like something you would put in a masters dissertation to sound smart.

_________________
nesdoug.com -- blog/tutorial on programming for the NES


Top
 Profile  
 
PostPosted: Sat Jan 21, 2017 10:22 am 
Online

Joined: Sun Sep 19, 2004 11:12 pm
Posts: 19113
Location: NE Indiana, USA (NTSC)
"Praxis" for "practice" is something I'd expect out of tech support scammers in India, who make a big deal about there being a "wirus" on the caller's "dextop".


Top
 Profile  
 
PostPosted: Sat Jan 21, 2017 10:57 am 
Offline

Joined: Tue May 28, 2013 5:49 am
Posts: 804
Location: Sweden
Heh, in Swedish "praxis" would be the proper word for the context used in this thread. But it's not totally nuancically equalent with the English "practice". For example you wouldn't use it like "you need more practice", in that case you would use "övning" (practice) or träning (training).


Top
 Profile  
 
PostPosted: Sat Jan 21, 2017 11:39 am 
Offline
Formerly WheelInventor

Joined: Thu Apr 14, 2016 2:55 am
Posts: 907
Location: Gothenburg, Sweden
dougeff wrote:
to sound smart

"praxis" would be rather neutral in swedish latin (like pokun said, proper, especially at work), but "modus operandi" certainly has a smartass flag attached to it outside criminology. Is that phrase even used outside criminology in english?

pokun wrote:
Nuancically equalent with the English "practice"

For this use, is there such a word? 'Praktik' might have been at one point, but i feel it is archaic when used as such compared to both 'praxis' and the english 'practice' (meaning mode of doing things). Arbetsmetod (Working method)?

_________________
http://www.frankengraphics.com - personal NES blog


Top
 Profile  
 
PostPosted: Sat Jan 21, 2017 12:18 pm 
Online

Joined: Sun Sep 19, 2004 11:12 pm
Posts: 19113
Location: NE Indiana, USA (NTSC)
WheelInventor wrote:
"modus operandi" certainly has a smartass flag attached to it outside criminology. Is that phrase even used outside criminology in english?

It may have passed from police procedural TV series into wider usage. One wiki describes the MediaWiki extension "AbuseFilter" as "useful to limit the damage caused by pattern vandals, or wiki vandals whose edits follow a very distinct m.o."


Top
 Profile  
 
PostPosted: Sat Jan 21, 2017 1:12 pm 
Offline
User avatar

Joined: Fri May 08, 2015 7:17 pm
Posts: 1780
Location: DIGDUG
You keep saying 'latin'. Praxis is a greek word...πρᾶξις

_________________
nesdoug.com -- blog/tutorial on programming for the NES


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 24 posts ]  Go to page 1, 2  Next

All times are UTC - 7 hours


Who is online

Users browsing this forum: No registered users and 8 guests


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
Powered by phpBB® Forum Software © phpBB Group