search

Hextris / hextris

Fast paced HTML5 puzzle game inspired by Tetris!
https://hextris.io
Other
2.21k stars 969 forks source link

Update documentation for main.js #174

Closed nicolaikozel closed 7 years ago

nicolaikozel commented 7 years ago

As part of my communication skills course 3I03 at McMaster University I am submitting this pull request (not to actually be merged) for bonus marks on my assignment.

I have gone through main.js and updated the documentation and commenting. I have followed the guidelines given in the course to add function declaration explanations, parameter clarifications, and inline comments describing the program in terms of the problem domain, summarising "what is happening next", justifying the design, and asserting conditions that must hold.

lengstrom commented 7 years ago

Hi @nicolaikozel. For the future, when commenting code you should do more than just translate the code into English. For example, a comment like (https://github.com/Hextris/hextris/pull/174/files#diff-77ab163850ef0fa98d6a9ee9fb6bbcafR231):

MainHex.delay = 15; //set delay to 15

Is not helpful at all, as you don't define what delay is, nor what the value 15 means. I'd recommend looking at the commenting section of these lecture notes to learn best practices for commenting: http://web.mit.edu/6.005/www/fa16/classes/04-code-review/#comments_where_needed

nicolaikozel commented 7 years ago

Thanks, like I said in my commit; this was just for my class and was done really quickly. This was really just a first draft. Thanks for the feedback though!

From: Logan Engstrom notifications@github.com Sent: February 20, 2017 9:11 PM To: Hextris/hextris Cc: Nicolai Kozel; Author Subject: Re: [Hextris/hextris] Update documentation for main.js (#174)

For the future, when commenting code you should do more than just translate the code into english. For example, a comment like (https://github.com/Hextris/hextris/pull/174/files#diff-77ab163850ef0fa98d6a9ee9fb6bbcafR231):

Update documentation for main.js by nicolaikozel · Pull Request #174 · Hextris/hextris · GitHubhttps://github.com/Hextris/hextris/pull/174/files#diff-77ab163850ef0fa98d6a9ee9fb6bbcafR231 github.com hextris - Fast paced HTML5 puzzle game inspired by Tetris!

MainHex.delay = 15; //set delay to 15

Is not helpful at all, as you don't define what delay is, nor what 15 even means. I'd recommend looking at the commenting section of this MIT course if you want to learn to comment better: http://web.mit.edu/6.005/www/fa16/classes/04-code-review/#comments_where_needed

Reading 4: Code Review - web.mit.eduhttp://web.mit.edu/6.005/www/fa16/classes/04-code-review/#comments_where_needed web.mit.edu Code review is careful, systematic study of source code by people who are not the original author of the code. It’s analogous to proofreading a term paper. Code ...

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHubhttps://github.com/Hextris/hextris/pull/174#issuecomment-281225636, or mute the threadhttps://github.com/notifications/unsubscribe-auth/AU_OBMPN5l1O7G1o-4k2F4H3rZVUbQqEks5reke-gaJpZM4MGjmE.